Player
The player API for audiobook apps written for an Audiobookshelf server (docs/server/player-apps.md).
Back to the web API reference.
Tells an app what the server is before it offers a sign-in.
Answers without a card: the version of the API it speaks and the sign-in methods an app may offer (a player password, and the browser sign-in).
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: none
-
200What an app checks before it offers a sign-in. Body:
Status(application/json)6 fieldsappstringrequiredAlways [STATUS_APP].serverVersionstringrequiredThe server release whose API this one answers like ([crate::COMPATIBLE_SERVER_VERSION]).isInitbooleanrequiredAlways true: the library is set up before an app can sign in.languagestringrequiredThe interface language apps show server text in.authMethodsarray of stringrequired[AUTH_METHODS].authFormDataAuthFormDatarequiredWhat the sign-in screen shows.
$ curl 'http://127.0.0.1:8787/player/status'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/status'
import requests
response = requests.get("http://127.0.0.1:8787/player/status")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/status");
console.log(response.status, await response.text());
let response = reqwest::get("http://127.0.0.1:8787/player/status").await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: What an app checks before it offers a sign-in.
{
"app": "audiobookshelf",
"serverVersion": "2.17.0",
"isInit": true,
"language": "en-us",
"authMethods": [
"local",
"openid"
],
"authFormData": {
"authLoginCustomMessage": "Sign in with a player password from Settings, Account, Player apps.",
"authOpenIDButtonText": "Sign in with the library",
"authOpenIDAutoLaunch": false
}
}
Schema:
{
"type": "object",
"description": "`GET /status`: what an app asks before it signs in.",
"required": [
"app",
"serverVersion",
"isInit",
"language",
"authMethods",
"authFormData"
],
"properties": {
"app": {
"type": "string",
"description": "Always [`STATUS_APP`].",
"example": "audiobookshelf"
},
"serverVersion": {
"type": "string",
"description": "The server release whose API this one answers like\n([`crate::COMPATIBLE_SERVER_VERSION`]).",
"example": "2.17.0"
},
"isInit": {
"type": "boolean",
"description": "Always true: the library is set up before an app can sign in.",
"example": true
},
"language": {
"type": "string",
"description": "The interface language apps show server text in.",
"example": "en-us"
},
"authMethods": {
"type": "array",
"items": {
"type": "string"
},
"description": "[`AUTH_METHODS`].",
"example": [
"local",
"openid"
]
},
"authFormData": {
"type": "object",
"description": "What the sign-in screen shows.",
"required": [
"authOpenIDButtonText",
"authOpenIDAutoLaunch"
],
"properties": {
"authLoginCustomMessage": {
"type": [
"string",
"null"
],
"description": "A note under the sign-in form: where to get a player password.",
"example": "Sign in with a player password from Settings, Account, Player apps."
},
"authOpenIDButtonText": {
"type": "string",
"description": "The label of the browser sign-in button.",
"example": "Sign in with the library"
},
"authOpenIDAutoLaunch": {
"type": "boolean",
"description": "Whether apps open the browser sign-in without a tap: never.",
"example": false
}
}
}
}
}
Answers that the player API is up, without a card.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: none
-
200The API answers. Body:
Ping(application/json)1 fieldsuccessbooleanrequiredAlways true.
$ curl 'http://127.0.0.1:8787/player/ping'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/ping'
import requests
response = requests.get("http://127.0.0.1:8787/player/ping")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/ping");
console.log(response.status, await response.text());
let response = reqwest::get("http://127.0.0.1:8787/player/ping").await?;
println!("{} {}", response.status(), response.text().await?);
Answers OK in plain text, without a card, for apps that check health.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: none
- 200
OK. Body: string (text/plain)
$ curl 'http://127.0.0.1:8787/player/healthcheck'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/healthcheck'
import requests
response = requests.get("http://127.0.0.1:8787/player/healthcheck")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/healthcheck");
console.log(response.status, await response.text());
let response = reqwest::get("http://127.0.0.1:8787/player/healthcheck").await?;
println!("{} {}", response.status(), response.text().await?);
Signs an app in with a username and a player password.
The username is the patron's sign-in name or email; the password is a player password from Account settings, never the account password.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: none
The sign-in name (or email) and a player password.
application/json: LoginBody
usernamestringrequiredThe patron's sign-in name or email address.passwordstringrequiredA player password from Account settings; the account password is never accepted.
-
200The patron, the card's tokens and settings. Body:
PlayerLoginResponse(application/json)5 fieldsuserUserrequiredThe signed-in patron, with the card's tokens.userDefaultLibraryIdstringrequiredThe library an app opens first: the whole library.serverSettingsServerSettingsrequiredSettings apps read at sign-in.ereaderDevicesarray of objectrequiredE-reader devices: always empty, the API serves no ebooks.SourcestringrequiredHow the server was installed; apps only display it.
- 400The body is not a JSON object with string
usernameandpassword. Astext/plain, when the body is not syntactically valid JSON. Body: string (text/plain) - 401No such player password, or it belongs to someone else. Body: string (
text/plain) - 403The patron must enroll a second factor first. Body: string (
text/plain) - 413The body is over 4 KiB. Body: string (
text/plain) - 415The request did not declare a JSON body. Body: string (
text/plain) - 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (
text/plain) - 500The library could not be read or written. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/login' \
-X POST \
-H 'Content-Type: application/json' \
-d '{"username": "riley", "password": "ABCDE-FGHJK-LMNPQ-RSTUV"}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/login' `
-Method Post `
-ContentType 'application/json' `
-Body '{"username": "riley", "password": "ABCDE-FGHJK-LMNPQ-RSTUV"}'
import requests
response = requests.post(
"http://127.0.0.1:8787/player/login",
json={"username": "riley", "password": "ABCDE-FGHJK-LMNPQ-RSTUV"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/login", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({"username": "riley", "password": "ABCDE-FGHJK-LMNPQ-RSTUV"}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/player/login")
.json(&serde_json::json!({"username": "riley", "password": "ABCDE-FGHJK-LMNPQ-RSTUV"}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The patron, the card's tokens and settings.
{
"user": {
"id": "li_8f14e45fceea467f",
"username": "riley",
"email": "riley@example.com",
"type": "user",
"token": "eyJhbGciOi...",
"accessToken": "eyJhbGciOi...",
"refreshToken": "eyJhbGciOi...",
"isOldToken": false,
"mediaProgress": [
{
"id": "li_8f14e45fceea467f",
"userId": "42",
"libraryItemId": "li_8f14e45fceea467f",
"episodeId": null,
"mediaItemId": "li_8f14e45fceea467f",
"mediaItemType": "book",
"duration": 36000.0,
"progress": 0.05,
"currentTime": 1830.5,
"isFinished": false,
"hideFromContinueListening": false,
"ebookLocation": null,
"ebookProgress": null,
"lastUpdate": 1763630000000,
"startedAt": 1763620000000,
"finishedAt": null
}
],
"seriesHideFromContinueListening": [],
"bookmarks": [
{
"libraryItemId": "li_8f14e45fceea467f",
"title": "The First",
"time": 1830.0,
"createdAt": 1763600000000
}
],
"isActive": true,
"isLocked": false,
"lastSeen": 1763630000000,
"createdAt": 1763600000000,
"permissions": {
"download": true,
"update": false,
"delete": false,
"upload": false,
"createEreader": false,
"accessAllLibraries": true,
"accessAllTags": true,
"accessExplicitContent": true,
"selectedTagsNotAccessible": false
},
"librariesAccessible": [
"bookclerk-library"
],
"itemTagsSelected": [],
"hasOpenIDLink": false
},
"userDefaultLibraryId": "bookclerk-library",
"serverSettings": {
"id": "li_8f14e45fceea467f",
"version": "2.17.0",
"buildNumber": 1,
"language": "en-us",
"dateFormat": "MM/dd/yyyy",
"timeFormat": "HH:mm",
"sortingIgnorePrefix": true,
"sortingPrefixes": [
"the",
"a"
],
"chromecastEnabled": false,
"homeBookshelfView": 1,
"bookshelfView": 1,
"authActiveAuthMethods": [
"local",
"openid"
],
"authOpenIDButtonText": "Sign in with the library",
"authOpenIDAutoLaunch": false,
"authLoginCustomMessage": "Sign in with a player password from Settings, Account, Player apps.",
"timeZone": "UTC"
},
"ereaderDevices": [],
"Source": "bookclerk"
}
Schema:
{
"type": "object",
"description": "The answer to a sign-in, a token refresh, `POST /api/authorize` and\nthe browser sign-in's callback.",
"required": [
"user",
"userDefaultLibraryId",
"serverSettings",
"ereaderDevices",
"Source"
],
"properties": {
"user": {
"type": "object",
"description": "The signed-in patron, with the card's tokens.",
"required": [
"id",
"username",
"type",
"token",
"isOldToken",
"mediaProgress",
"seriesHideFromContinueListening",
"bookmarks",
"isActive",
"isLocked",
"createdAt",
"permissions",
"librariesAccessible",
"itemTagsSelected",
"hasOpenIDLink"
],
"properties": {
"id": {
"type": "string",
"description": "The patron's portal identity id, as a string.",
"example": "li_8f14e45fceea467f"
},
"username": {
"type": "string",
"description": "The name the patron signs in with.",
"example": "riley"
},
"email": {
"type": [
"string",
"null"
],
"description": "The patron's email address, if the library has one.",
"example": "riley@example.com"
},
"type": {
"type": "string",
"description": "Always `user`: no app is given administrator powers.",
"example": "user"
},
"token": {
"type": "string",
"description": "The access token, for apps that read it from here (older apps\nsend this one as their bearer). Empty where the answer is not a\nsign-in.",
"example": "eyJhbGciOi..."
},
"accessToken": {
"type": [
"string",
"null"
],
"description": "The card's access token, on sign-in and refresh answers only.",
"example": "eyJhbGciOi..."
},
"refreshToken": {
"type": [
"string",
"null"
],
"description": "The card's refresh token, on sign-in and refresh answers only.",
"example": "eyJhbGciOi..."
},
"isOldToken": {
"type": "boolean",
"description": "Always false: tokens are never the old non-expiring kind.",
"example": false
},
"mediaProgress": {
"type": "array",
"items": {
"type": "object",
"description": "The patron's progress on one item.",
"required": [
"id",
"userId",
"libraryItemId",
"mediaItemId",
"mediaItemType",
"duration",
"progress",
"currentTime",
"isFinished",
"hideFromContinueListening",
"lastUpdate",
"startedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The progress id: the item id (one record per patron and item).",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaItemId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"mediaItemType": {
"type": "string",
"description": "Always `book`.",
"example": "book"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds, as last reported.",
"example": 36000.0
},
"progress": {
"type": "number",
"format": "double",
"description": "The share listened, from 0 to 1.",
"example": 0.05
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished it.",
"example": false
},
"hideFromContinueListening": {
"type": "boolean",
"description": "Whether it is hidden from continue listening.",
"example": false
},
"ebookLocation": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"ebookProgress": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Always null.",
"example": null
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When the progress last changed, in epoch milliseconds.",
"example": 1763630000000
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the patron started, in epoch milliseconds.",
"example": 1763620000000
},
"finishedAt": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron finished, in epoch milliseconds.",
"example": null
}
}
},
"description": "Progress on every item the patron has started."
},
"seriesHideFromContinueListening": {
"type": "array",
"items": {
"type": "string"
},
"description": "Series hidden from continue listening: none.",
"example": []
},
"bookmarks": {
"type": "array",
"items": {
"type": "object",
"description": "A bookmark.",
"required": [
"libraryItemId",
"title",
"time",
"createdAt"
],
"properties": {
"libraryItemId": {
"type": "string",
"description": "The item it is in.",
"example": "li_8f14e45fceea467f"
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
},
"time": {
"type": "number",
"format": "double",
"description": "Where it is, in seconds.",
"example": 1830.0
},
"createdAt": {
"type": "integer",
"format": "int64",
"description": "When it was made, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"description": "Every bookmark the patron has made."
},
"isActive": {
"type": "boolean",
"description": "Always true: a disabled patron cannot sign in.",
"example": true
},
"isLocked": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"lastSeen": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron was last seen, in epoch milliseconds.",
"example": 1763630000000
},
"createdAt": {
"type": "integer",
"format": "int64",
"description": "When the patron joined, in epoch milliseconds.",
"example": 1763600000000
},
"permissions": {
"type": "object",
"description": "What the patron may do.",
"required": [
"download",
"update",
"delete",
"upload",
"createEreader",
"accessAllLibraries",
"accessAllTags",
"accessExplicitContent",
"selectedTagsNotAccessible"
],
"properties": {
"download": {
"type": "boolean",
"description": "Whether the patron may download items to the device.",
"example": true
},
"update": {
"type": "boolean",
"description": "Always false: apps edit nothing.",
"example": false
},
"delete": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"upload": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"createEreader": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"accessAllLibraries": {
"type": "boolean",
"description": "Always true: the libraries listed are the ones the patron sees.",
"example": true
},
"accessAllTags": {
"type": "boolean",
"description": "Always true.",
"example": true
},
"accessExplicitContent": {
"type": "boolean",
"description": "Always true: scope, not an explicit flag, decides visibility.",
"example": true
},
"selectedTagsNotAccessible": {
"type": "boolean",
"description": "Always false.",
"example": false
}
}
},
"librariesAccessible": {
"type": "array",
"items": {
"type": "string"
},
"description": "Libraries the patron may open, by id.",
"example": [
"bookclerk-library"
]
},
"itemTagsSelected": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags that limit what the patron sees: none (scope is applied by\nthe host, not by tags).",
"example": []
},
"hasOpenIDLink": {
"type": "boolean",
"description": "Whether the patron signed in through the browser at least once.",
"example": false
}
}
},
"userDefaultLibraryId": {
"type": "string",
"description": "The library an app opens first: the whole library.",
"example": "bookclerk-library"
},
"serverSettings": {
"type": "object",
"description": "Settings apps read at sign-in.",
"required": [
"id",
"version",
"buildNumber",
"language",
"dateFormat",
"timeFormat",
"sortingIgnorePrefix",
"sortingPrefixes",
"chromecastEnabled",
"homeBookshelfView",
"bookshelfView",
"authActiveAuthMethods",
"authOpenIDButtonText",
"authOpenIDAutoLaunch",
"timeZone"
],
"properties": {
"id": {
"type": "string",
"description": "Always `server-settings`.",
"example": "li_8f14e45fceea467f"
},
"version": {
"type": "string",
"description": "[`crate::COMPATIBLE_SERVER_VERSION`]: apps turn features on by it.",
"example": "2.17.0"
},
"buildNumber": {
"type": "integer",
"format": "int32",
"description": "Always 1.",
"example": 1,
"minimum": 0
},
"language": {
"type": "string",
"description": "The interface language.",
"example": "en-us"
},
"dateFormat": {
"type": "string",
"description": "How apps format dates.",
"example": "MM/dd/yyyy"
},
"timeFormat": {
"type": "string",
"description": "How apps format times.",
"example": "HH:mm"
},
"sortingIgnorePrefix": {
"type": "boolean",
"description": "Whether sorting skips leading articles: no.",
"example": true
},
"sortingPrefixes": {
"type": "array",
"items": {
"type": "string"
},
"description": "The articles sorting would skip.",
"example": [
"the",
"a"
]
},
"chromecastEnabled": {
"type": "boolean",
"description": "Whether apps offer casting: no.",
"example": false
},
"homeBookshelfView": {
"type": "integer",
"format": "int32",
"description": "The home shelf style (1: standard).",
"example": 1,
"minimum": 0
},
"bookshelfView": {
"type": "integer",
"format": "int32",
"description": "The library shelf style (1: standard).",
"example": 1,
"minimum": 0
},
"authActiveAuthMethods": {
"type": "array",
"items": {
"type": "string"
},
"description": "[`AUTH_METHODS`].",
"example": [
"local",
"openid"
]
},
"authOpenIDButtonText": {
"type": "string",
"description": "The browser sign-in button's label.",
"example": "Sign in with the library"
},
"authOpenIDAutoLaunch": {
"type": "boolean",
"description": "Never true.",
"example": false
},
"authLoginCustomMessage": {
"type": [
"string",
"null"
],
"description": "The sign-in screen's note.",
"example": "Sign in with a player password from Settings, Account, Player apps."
},
"timeZone": {
"type": "string",
"description": "The host's time zone name, or UTC.",
"example": "UTC"
}
}
},
"ereaderDevices": {
"type": "array",
"items": {
"type": "object"
},
"description": "E-reader devices: always empty, the API serves no ebooks.",
"example": []
},
"Source": {
"type": "string",
"description": "How the server was installed; apps only display it.",
"example": "bookclerk"
}
}
}
Status 400: The body is not a JSON object with string username and password. As text/plain, when the body is not syntactically valid JSON.
Failed to parse the request body as JSON: expected value at line 1 column 1
Schema:
A text/plain body: a string.
Status 401: No such player password, or it belongs to someone else.
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor first.
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 413: The body is over 4 KiB.
Payload Too Large
Schema:
A text/plain body: a string.
Status 415: The request did not declare a JSON body.
Expected request with `Content-Type: application/json`
Schema:
A text/plain body: a string.
Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.
Failed to deserialize the JSON body into the target type: missing field `username` at line 1 column 2
Schema:
A text/plain body: a string.
Status 500: The library could not be read or written.
Internal Server Error
Schema:
A text/plain body: a string.
Trades a refresh token for a new access and refresh token.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: none
x-refresh-tokenheaderstringrequiredThe card's refresh token.
-
200The patron and the card's new tokens. Body:
PlayerLoginResponse(application/json)5 fieldsuserUserrequiredThe signed-in patron, with the card's tokens.userDefaultLibraryIdstringrequiredThe library an app opens first: the whole library.serverSettingsServerSettingsrequiredSettings apps read at sign-in.ereaderDevicesarray of objectrequiredE-reader devices: always empty, the API serves no ebooks.SourcestringrequiredHow the server was installed; apps only display it.
- 401No such live refresh token. Body: string (
text/plain) - 403The patron must enroll a second factor first. Body: string (
text/plain) - 500The library could not be read or written. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/auth/refresh' \
-X POST
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/auth/refresh' `
-Method Post
import requests
response = requests.post("http://127.0.0.1:8787/player/auth/refresh")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/auth/refresh", {
method: "POST",
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/player/auth/refresh")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The patron and the card's new tokens.
{
"user": {
"id": "li_8f14e45fceea467f",
"username": "riley",
"email": "riley@example.com",
"type": "user",
"token": "eyJhbGciOi...",
"accessToken": "eyJhbGciOi...",
"refreshToken": "eyJhbGciOi...",
"isOldToken": false,
"mediaProgress": [
{
"id": "li_8f14e45fceea467f",
"userId": "42",
"libraryItemId": "li_8f14e45fceea467f",
"episodeId": null,
"mediaItemId": "li_8f14e45fceea467f",
"mediaItemType": "book",
"duration": 36000.0,
"progress": 0.05,
"currentTime": 1830.5,
"isFinished": false,
"hideFromContinueListening": false,
"ebookLocation": null,
"ebookProgress": null,
"lastUpdate": 1763630000000,
"startedAt": 1763620000000,
"finishedAt": null
}
],
"seriesHideFromContinueListening": [],
"bookmarks": [
{
"libraryItemId": "li_8f14e45fceea467f",
"title": "The First",
"time": 1830.0,
"createdAt": 1763600000000
}
],
"isActive": true,
"isLocked": false,
"lastSeen": 1763630000000,
"createdAt": 1763600000000,
"permissions": {
"download": true,
"update": false,
"delete": false,
"upload": false,
"createEreader": false,
"accessAllLibraries": true,
"accessAllTags": true,
"accessExplicitContent": true,
"selectedTagsNotAccessible": false
},
"librariesAccessible": [
"bookclerk-library"
],
"itemTagsSelected": [],
"hasOpenIDLink": false
},
"userDefaultLibraryId": "bookclerk-library",
"serverSettings": {
"id": "li_8f14e45fceea467f",
"version": "2.17.0",
"buildNumber": 1,
"language": "en-us",
"dateFormat": "MM/dd/yyyy",
"timeFormat": "HH:mm",
"sortingIgnorePrefix": true,
"sortingPrefixes": [
"the",
"a"
],
"chromecastEnabled": false,
"homeBookshelfView": 1,
"bookshelfView": 1,
"authActiveAuthMethods": [
"local",
"openid"
],
"authOpenIDButtonText": "Sign in with the library",
"authOpenIDAutoLaunch": false,
"authLoginCustomMessage": "Sign in with a player password from Settings, Account, Player apps.",
"timeZone": "UTC"
},
"ereaderDevices": [],
"Source": "bookclerk"
}
Schema:
{
"type": "object",
"description": "The answer to a sign-in, a token refresh, `POST /api/authorize` and\nthe browser sign-in's callback.",
"required": [
"user",
"userDefaultLibraryId",
"serverSettings",
"ereaderDevices",
"Source"
],
"properties": {
"user": {
"type": "object",
"description": "The signed-in patron, with the card's tokens.",
"required": [
"id",
"username",
"type",
"token",
"isOldToken",
"mediaProgress",
"seriesHideFromContinueListening",
"bookmarks",
"isActive",
"isLocked",
"createdAt",
"permissions",
"librariesAccessible",
"itemTagsSelected",
"hasOpenIDLink"
],
"properties": {
"id": {
"type": "string",
"description": "The patron's portal identity id, as a string.",
"example": "li_8f14e45fceea467f"
},
"username": {
"type": "string",
"description": "The name the patron signs in with.",
"example": "riley"
},
"email": {
"type": [
"string",
"null"
],
"description": "The patron's email address, if the library has one.",
"example": "riley@example.com"
},
"type": {
"type": "string",
"description": "Always `user`: no app is given administrator powers.",
"example": "user"
},
"token": {
"type": "string",
"description": "The access token, for apps that read it from here (older apps\nsend this one as their bearer). Empty where the answer is not a\nsign-in.",
"example": "eyJhbGciOi..."
},
"accessToken": {
"type": [
"string",
"null"
],
"description": "The card's access token, on sign-in and refresh answers only.",
"example": "eyJhbGciOi..."
},
"refreshToken": {
"type": [
"string",
"null"
],
"description": "The card's refresh token, on sign-in and refresh answers only.",
"example": "eyJhbGciOi..."
},
"isOldToken": {
"type": "boolean",
"description": "Always false: tokens are never the old non-expiring kind.",
"example": false
},
"mediaProgress": {
"type": "array",
"items": {
"type": "object",
"description": "The patron's progress on one item.",
"required": [
"id",
"userId",
"libraryItemId",
"mediaItemId",
"mediaItemType",
"duration",
"progress",
"currentTime",
"isFinished",
"hideFromContinueListening",
"lastUpdate",
"startedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The progress id: the item id (one record per patron and item).",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaItemId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"mediaItemType": {
"type": "string",
"description": "Always `book`.",
"example": "book"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds, as last reported.",
"example": 36000.0
},
"progress": {
"type": "number",
"format": "double",
"description": "The share listened, from 0 to 1.",
"example": 0.05
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished it.",
"example": false
},
"hideFromContinueListening": {
"type": "boolean",
"description": "Whether it is hidden from continue listening.",
"example": false
},
"ebookLocation": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"ebookProgress": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Always null.",
"example": null
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When the progress last changed, in epoch milliseconds.",
"example": 1763630000000
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the patron started, in epoch milliseconds.",
"example": 1763620000000
},
"finishedAt": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron finished, in epoch milliseconds.",
"example": null
}
}
},
"description": "Progress on every item the patron has started."
},
"seriesHideFromContinueListening": {
"type": "array",
"items": {
"type": "string"
},
"description": "Series hidden from continue listening: none.",
"example": []
},
"bookmarks": {
"type": "array",
"items": {
"type": "object",
"description": "A bookmark.",
"required": [
"libraryItemId",
"title",
"time",
"createdAt"
],
"properties": {
"libraryItemId": {
"type": "string",
"description": "The item it is in.",
"example": "li_8f14e45fceea467f"
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
},
"time": {
"type": "number",
"format": "double",
"description": "Where it is, in seconds.",
"example": 1830.0
},
"createdAt": {
"type": "integer",
"format": "int64",
"description": "When it was made, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"description": "Every bookmark the patron has made."
},
"isActive": {
"type": "boolean",
"description": "Always true: a disabled patron cannot sign in.",
"example": true
},
"isLocked": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"lastSeen": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron was last seen, in epoch milliseconds.",
"example": 1763630000000
},
"createdAt": {
"type": "integer",
"format": "int64",
"description": "When the patron joined, in epoch milliseconds.",
"example": 1763600000000
},
"permissions": {
"type": "object",
"description": "What the patron may do.",
"required": [
"download",
"update",
"delete",
"upload",
"createEreader",
"accessAllLibraries",
"accessAllTags",
"accessExplicitContent",
"selectedTagsNotAccessible"
],
"properties": {
"download": {
"type": "boolean",
"description": "Whether the patron may download items to the device.",
"example": true
},
"update": {
"type": "boolean",
"description": "Always false: apps edit nothing.",
"example": false
},
"delete": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"upload": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"createEreader": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"accessAllLibraries": {
"type": "boolean",
"description": "Always true: the libraries listed are the ones the patron sees.",
"example": true
},
"accessAllTags": {
"type": "boolean",
"description": "Always true.",
"example": true
},
"accessExplicitContent": {
"type": "boolean",
"description": "Always true: scope, not an explicit flag, decides visibility.",
"example": true
},
"selectedTagsNotAccessible": {
"type": "boolean",
"description": "Always false.",
"example": false
}
}
},
"librariesAccessible": {
"type": "array",
"items": {
"type": "string"
},
"description": "Libraries the patron may open, by id.",
"example": [
"bookclerk-library"
]
},
"itemTagsSelected": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags that limit what the patron sees: none (scope is applied by\nthe host, not by tags).",
"example": []
},
"hasOpenIDLink": {
"type": "boolean",
"description": "Whether the patron signed in through the browser at least once.",
"example": false
}
}
},
"userDefaultLibraryId": {
"type": "string",
"description": "The library an app opens first: the whole library.",
"example": "bookclerk-library"
},
"serverSettings": {
"type": "object",
"description": "Settings apps read at sign-in.",
"required": [
"id",
"version",
"buildNumber",
"language",
"dateFormat",
"timeFormat",
"sortingIgnorePrefix",
"sortingPrefixes",
"chromecastEnabled",
"homeBookshelfView",
"bookshelfView",
"authActiveAuthMethods",
"authOpenIDButtonText",
"authOpenIDAutoLaunch",
"timeZone"
],
"properties": {
"id": {
"type": "string",
"description": "Always `server-settings`.",
"example": "li_8f14e45fceea467f"
},
"version": {
"type": "string",
"description": "[`crate::COMPATIBLE_SERVER_VERSION`]: apps turn features on by it.",
"example": "2.17.0"
},
"buildNumber": {
"type": "integer",
"format": "int32",
"description": "Always 1.",
"example": 1,
"minimum": 0
},
"language": {
"type": "string",
"description": "The interface language.",
"example": "en-us"
},
"dateFormat": {
"type": "string",
"description": "How apps format dates.",
"example": "MM/dd/yyyy"
},
"timeFormat": {
"type": "string",
"description": "How apps format times.",
"example": "HH:mm"
},
"sortingIgnorePrefix": {
"type": "boolean",
"description": "Whether sorting skips leading articles: no.",
"example": true
},
"sortingPrefixes": {
"type": "array",
"items": {
"type": "string"
},
"description": "The articles sorting would skip.",
"example": [
"the",
"a"
]
},
"chromecastEnabled": {
"type": "boolean",
"description": "Whether apps offer casting: no.",
"example": false
},
"homeBookshelfView": {
"type": "integer",
"format": "int32",
"description": "The home shelf style (1: standard).",
"example": 1,
"minimum": 0
},
"bookshelfView": {
"type": "integer",
"format": "int32",
"description": "The library shelf style (1: standard).",
"example": 1,
"minimum": 0
},
"authActiveAuthMethods": {
"type": "array",
"items": {
"type": "string"
},
"description": "[`AUTH_METHODS`].",
"example": [
"local",
"openid"
]
},
"authOpenIDButtonText": {
"type": "string",
"description": "The browser sign-in button's label.",
"example": "Sign in with the library"
},
"authOpenIDAutoLaunch": {
"type": "boolean",
"description": "Never true.",
"example": false
},
"authLoginCustomMessage": {
"type": [
"string",
"null"
],
"description": "The sign-in screen's note.",
"example": "Sign in with a player password from Settings, Account, Player apps."
},
"timeZone": {
"type": "string",
"description": "The host's time zone name, or UTC.",
"example": "UTC"
}
}
},
"ereaderDevices": {
"type": "array",
"items": {
"type": "object"
},
"description": "E-reader devices: always empty, the API serves no ebooks.",
"example": []
},
"Source": {
"type": "string",
"description": "How the server was installed; apps only display it.",
"example": "bookclerk"
}
}
}
Status 401: No such live refresh token.
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor first.
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 500: The library could not be read or written.
Internal Server Error
Schema:
A text/plain body: a string.
Ends the card a refresh token (or the bearer access token) belongs to.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: none
x-refresh-tokenheaderstring or nullThe card's refresh token; without it, the bearer access token names the card.
- 200
OK, whether or not a card was live. Body: string (text/plain) - 500The library could not be written. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/logout' \
-X POST
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/logout' `
-Method Post
import requests
response = requests.post("http://127.0.0.1:8787/player/logout")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/logout", {
method: "POST",
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/player/logout")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Starts the browser sign-in: answers a 302 to the library's consent page, which the app opens in a browser.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: none
code_challengequerystringrequiredPKCE S256 challenge.code_challenge_methodquerystringrequiredS256.redirect_uriquerystringrequiredThe app's address:audiobookshelf://oauth,absorb://oauthorlissen://oauth.client_idquerystringThe app's own name; echoed.response_typequerystringcode.statequerystringHanded back to the app with the code.
- 302
Locationis the consent page, with the parameters the app passes on. No body. - 400A parameter is missing or malformed, or the app is not one the library returns to (
Invalid redirect_uri). Body: string (text/plain)
$ curl 'http://127.0.0.1:8787/player/auth/openid?code_challenge=string&code_challenge_method=string&redirect_uri=string'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/auth/openid?code_challenge=string&code_challenge_method=string&redirect_uri=string'
import requests
response = requests.get("http://127.0.0.1:8787/player/auth/openid?code_challenge=string&code_challenge_method=string&redirect_uri=string")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/auth/openid?code_challenge=string&code_challenge_method=string&redirect_uri=string");
console.log(response.status, await response.text());
let response = reqwest::get("http://127.0.0.1:8787/player/auth/openid?code_challenge=string&code_challenge_method=string&redirect_uri=string").await?;
println!("{} {}", response.status(), response.text().await?);
Sends the browser back to the app with the code (or the refusal).
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: none
appquerystringrequiredThe app's address, one the library returns to.codequerystringThe code; absent when the patron declined.statequerystringThe app's state.
- 302
Locationis the app's address withcodeandstate(orerror=access_denied). No body. - 400The app is not one the library returns to, or a parameter is malformed. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/auth/openid/mobile-redirect?app=string'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/auth/openid/mobile-redirect?app=string'
import requests
response = requests.get("http://127.0.0.1:8787/player/auth/openid/mobile-redirect?app=string")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/auth/openid/mobile-redirect?app=string");
console.log(response.status, await response.text());
let response = reqwest::get("http://127.0.0.1:8787/player/auth/openid/mobile-redirect?app=string").await?;
println!("{} {}", response.status(), response.text().await?);
Trades a browser sign-in's code and PKCE verifier for a card.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: none
codequerystringrequiredThe code the app was handed.code_verifierquerystringrequiredThe PKCE verifier.statequerystringThe app's state; not read.
-
200The patron, the card's tokens and settings. Body:
PlayerLoginResponse(application/json)5 fieldsuserUserrequiredThe signed-in patron, with the card's tokens.userDefaultLibraryIdstringrequiredThe library an app opens first: the whole library.serverSettingsServerSettingsrequiredSettings apps read at sign-in.ereaderDevicesarray of objectrequiredE-reader devices: always empty, the API serves no ebooks.SourcestringrequiredHow the server was installed; apps only display it.
- 400The code or verifier is missing or malformed. Body: string (
text/plain) - 401The code is unknown, spent, expired, or does not match the verifier. Body: string (
text/plain) - 403The patron must enroll a second factor first. Body: string (
text/plain) - 500The library could not be read or written. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/auth/openid/callback?code=string&code_verifier=string'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/auth/openid/callback?code=string&code_verifier=string'
import requests
response = requests.get("http://127.0.0.1:8787/player/auth/openid/callback?code=string&code_verifier=string")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/auth/openid/callback?code=string&code_verifier=string");
console.log(response.status, await response.text());
let response = reqwest::get("http://127.0.0.1:8787/player/auth/openid/callback?code=string&code_verifier=string").await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The patron, the card's tokens and settings.
{
"user": {
"id": "li_8f14e45fceea467f",
"username": "riley",
"email": "riley@example.com",
"type": "user",
"token": "eyJhbGciOi...",
"accessToken": "eyJhbGciOi...",
"refreshToken": "eyJhbGciOi...",
"isOldToken": false,
"mediaProgress": [
{
"id": "li_8f14e45fceea467f",
"userId": "42",
"libraryItemId": "li_8f14e45fceea467f",
"episodeId": null,
"mediaItemId": "li_8f14e45fceea467f",
"mediaItemType": "book",
"duration": 36000.0,
"progress": 0.05,
"currentTime": 1830.5,
"isFinished": false,
"hideFromContinueListening": false,
"ebookLocation": null,
"ebookProgress": null,
"lastUpdate": 1763630000000,
"startedAt": 1763620000000,
"finishedAt": null
}
],
"seriesHideFromContinueListening": [],
"bookmarks": [
{
"libraryItemId": "li_8f14e45fceea467f",
"title": "The First",
"time": 1830.0,
"createdAt": 1763600000000
}
],
"isActive": true,
"isLocked": false,
"lastSeen": 1763630000000,
"createdAt": 1763600000000,
"permissions": {
"download": true,
"update": false,
"delete": false,
"upload": false,
"createEreader": false,
"accessAllLibraries": true,
"accessAllTags": true,
"accessExplicitContent": true,
"selectedTagsNotAccessible": false
},
"librariesAccessible": [
"bookclerk-library"
],
"itemTagsSelected": [],
"hasOpenIDLink": false
},
"userDefaultLibraryId": "bookclerk-library",
"serverSettings": {
"id": "li_8f14e45fceea467f",
"version": "2.17.0",
"buildNumber": 1,
"language": "en-us",
"dateFormat": "MM/dd/yyyy",
"timeFormat": "HH:mm",
"sortingIgnorePrefix": true,
"sortingPrefixes": [
"the",
"a"
],
"chromecastEnabled": false,
"homeBookshelfView": 1,
"bookshelfView": 1,
"authActiveAuthMethods": [
"local",
"openid"
],
"authOpenIDButtonText": "Sign in with the library",
"authOpenIDAutoLaunch": false,
"authLoginCustomMessage": "Sign in with a player password from Settings, Account, Player apps.",
"timeZone": "UTC"
},
"ereaderDevices": [],
"Source": "bookclerk"
}
Schema:
{
"type": "object",
"description": "The answer to a sign-in, a token refresh, `POST /api/authorize` and\nthe browser sign-in's callback.",
"required": [
"user",
"userDefaultLibraryId",
"serverSettings",
"ereaderDevices",
"Source"
],
"properties": {
"user": {
"type": "object",
"description": "The signed-in patron, with the card's tokens.",
"required": [
"id",
"username",
"type",
"token",
"isOldToken",
"mediaProgress",
"seriesHideFromContinueListening",
"bookmarks",
"isActive",
"isLocked",
"createdAt",
"permissions",
"librariesAccessible",
"itemTagsSelected",
"hasOpenIDLink"
],
"properties": {
"id": {
"type": "string",
"description": "The patron's portal identity id, as a string.",
"example": "li_8f14e45fceea467f"
},
"username": {
"type": "string",
"description": "The name the patron signs in with.",
"example": "riley"
},
"email": {
"type": [
"string",
"null"
],
"description": "The patron's email address, if the library has one.",
"example": "riley@example.com"
},
"type": {
"type": "string",
"description": "Always `user`: no app is given administrator powers.",
"example": "user"
},
"token": {
"type": "string",
"description": "The access token, for apps that read it from here (older apps\nsend this one as their bearer). Empty where the answer is not a\nsign-in.",
"example": "eyJhbGciOi..."
},
"accessToken": {
"type": [
"string",
"null"
],
"description": "The card's access token, on sign-in and refresh answers only.",
"example": "eyJhbGciOi..."
},
"refreshToken": {
"type": [
"string",
"null"
],
"description": "The card's refresh token, on sign-in and refresh answers only.",
"example": "eyJhbGciOi..."
},
"isOldToken": {
"type": "boolean",
"description": "Always false: tokens are never the old non-expiring kind.",
"example": false
},
"mediaProgress": {
"type": "array",
"items": {
"type": "object",
"description": "The patron's progress on one item.",
"required": [
"id",
"userId",
"libraryItemId",
"mediaItemId",
"mediaItemType",
"duration",
"progress",
"currentTime",
"isFinished",
"hideFromContinueListening",
"lastUpdate",
"startedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The progress id: the item id (one record per patron and item).",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaItemId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"mediaItemType": {
"type": "string",
"description": "Always `book`.",
"example": "book"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds, as last reported.",
"example": 36000.0
},
"progress": {
"type": "number",
"format": "double",
"description": "The share listened, from 0 to 1.",
"example": 0.05
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished it.",
"example": false
},
"hideFromContinueListening": {
"type": "boolean",
"description": "Whether it is hidden from continue listening.",
"example": false
},
"ebookLocation": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"ebookProgress": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Always null.",
"example": null
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When the progress last changed, in epoch milliseconds.",
"example": 1763630000000
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the patron started, in epoch milliseconds.",
"example": 1763620000000
},
"finishedAt": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron finished, in epoch milliseconds.",
"example": null
}
}
},
"description": "Progress on every item the patron has started."
},
"seriesHideFromContinueListening": {
"type": "array",
"items": {
"type": "string"
},
"description": "Series hidden from continue listening: none.",
"example": []
},
"bookmarks": {
"type": "array",
"items": {
"type": "object",
"description": "A bookmark.",
"required": [
"libraryItemId",
"title",
"time",
"createdAt"
],
"properties": {
"libraryItemId": {
"type": "string",
"description": "The item it is in.",
"example": "li_8f14e45fceea467f"
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
},
"time": {
"type": "number",
"format": "double",
"description": "Where it is, in seconds.",
"example": 1830.0
},
"createdAt": {
"type": "integer",
"format": "int64",
"description": "When it was made, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"description": "Every bookmark the patron has made."
},
"isActive": {
"type": "boolean",
"description": "Always true: a disabled patron cannot sign in.",
"example": true
},
"isLocked": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"lastSeen": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron was last seen, in epoch milliseconds.",
"example": 1763630000000
},
"createdAt": {
"type": "integer",
"format": "int64",
"description": "When the patron joined, in epoch milliseconds.",
"example": 1763600000000
},
"permissions": {
"type": "object",
"description": "What the patron may do.",
"required": [
"download",
"update",
"delete",
"upload",
"createEreader",
"accessAllLibraries",
"accessAllTags",
"accessExplicitContent",
"selectedTagsNotAccessible"
],
"properties": {
"download": {
"type": "boolean",
"description": "Whether the patron may download items to the device.",
"example": true
},
"update": {
"type": "boolean",
"description": "Always false: apps edit nothing.",
"example": false
},
"delete": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"upload": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"createEreader": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"accessAllLibraries": {
"type": "boolean",
"description": "Always true: the libraries listed are the ones the patron sees.",
"example": true
},
"accessAllTags": {
"type": "boolean",
"description": "Always true.",
"example": true
},
"accessExplicitContent": {
"type": "boolean",
"description": "Always true: scope, not an explicit flag, decides visibility.",
"example": true
},
"selectedTagsNotAccessible": {
"type": "boolean",
"description": "Always false.",
"example": false
}
}
},
"librariesAccessible": {
"type": "array",
"items": {
"type": "string"
},
"description": "Libraries the patron may open, by id.",
"example": [
"bookclerk-library"
]
},
"itemTagsSelected": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags that limit what the patron sees: none (scope is applied by\nthe host, not by tags).",
"example": []
},
"hasOpenIDLink": {
"type": "boolean",
"description": "Whether the patron signed in through the browser at least once.",
"example": false
}
}
},
"userDefaultLibraryId": {
"type": "string",
"description": "The library an app opens first: the whole library.",
"example": "bookclerk-library"
},
"serverSettings": {
"type": "object",
"description": "Settings apps read at sign-in.",
"required": [
"id",
"version",
"buildNumber",
"language",
"dateFormat",
"timeFormat",
"sortingIgnorePrefix",
"sortingPrefixes",
"chromecastEnabled",
"homeBookshelfView",
"bookshelfView",
"authActiveAuthMethods",
"authOpenIDButtonText",
"authOpenIDAutoLaunch",
"timeZone"
],
"properties": {
"id": {
"type": "string",
"description": "Always `server-settings`.",
"example": "li_8f14e45fceea467f"
},
"version": {
"type": "string",
"description": "[`crate::COMPATIBLE_SERVER_VERSION`]: apps turn features on by it.",
"example": "2.17.0"
},
"buildNumber": {
"type": "integer",
"format": "int32",
"description": "Always 1.",
"example": 1,
"minimum": 0
},
"language": {
"type": "string",
"description": "The interface language.",
"example": "en-us"
},
"dateFormat": {
"type": "string",
"description": "How apps format dates.",
"example": "MM/dd/yyyy"
},
"timeFormat": {
"type": "string",
"description": "How apps format times.",
"example": "HH:mm"
},
"sortingIgnorePrefix": {
"type": "boolean",
"description": "Whether sorting skips leading articles: no.",
"example": true
},
"sortingPrefixes": {
"type": "array",
"items": {
"type": "string"
},
"description": "The articles sorting would skip.",
"example": [
"the",
"a"
]
},
"chromecastEnabled": {
"type": "boolean",
"description": "Whether apps offer casting: no.",
"example": false
},
"homeBookshelfView": {
"type": "integer",
"format": "int32",
"description": "The home shelf style (1: standard).",
"example": 1,
"minimum": 0
},
"bookshelfView": {
"type": "integer",
"format": "int32",
"description": "The library shelf style (1: standard).",
"example": 1,
"minimum": 0
},
"authActiveAuthMethods": {
"type": "array",
"items": {
"type": "string"
},
"description": "[`AUTH_METHODS`].",
"example": [
"local",
"openid"
]
},
"authOpenIDButtonText": {
"type": "string",
"description": "The browser sign-in button's label.",
"example": "Sign in with the library"
},
"authOpenIDAutoLaunch": {
"type": "boolean",
"description": "Never true.",
"example": false
},
"authLoginCustomMessage": {
"type": [
"string",
"null"
],
"description": "The sign-in screen's note.",
"example": "Sign in with a player password from Settings, Account, Player apps."
},
"timeZone": {
"type": "string",
"description": "The host's time zone name, or UTC.",
"example": "UTC"
}
}
},
"ereaderDevices": {
"type": "array",
"items": {
"type": "object"
},
"description": "E-reader devices: always empty, the API serves no ebooks.",
"example": []
},
"Source": {
"type": "string",
"description": "How the server was installed; apps only display it.",
"example": "bookclerk"
}
}
}
Status 400: The code or verifier is missing or malformed.
Bad Request
Schema:
A text/plain body: a string.
Status 401: The code is unknown, spent, expired, or does not match the verifier.
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor first.
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 500: The library could not be read or written.
Internal Server Error
Schema:
A text/plain body: a string.
Opens the live socket.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: none
EIOquerystringrequired4.transportquerystringrequiredwebsocket; long polling is not served.
- 101Switching to the Socket.IO websocket. No body.
- 400Not a websocket upgrade, another Engine.IO revision, or long polling. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/socket.io/?EIO=string&transport=string'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/socket.io/?EIO=string&transport=string'
import requests
response = requests.get("http://127.0.0.1:8787/player/socket.io/?EIO=string&transport=string")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/socket.io/?EIO=string&transport=string");
console.log(response.status, await response.text());
let response = reqwest::get("http://127.0.0.1:8787/player/socket.io/?EIO=string&transport=string").await?;
println!("{} {}", response.status(), response.text().await?);
Opens the live socket for a client that drops the trailing slash; the
same socket as [get_socket].
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: none
EIOquerystringrequired4.transportquerystringrequiredwebsocket; long polling is not served.
- 101Switching to the Socket.IO websocket. No body.
- 400Not a websocket upgrade, another Engine.IO revision, or long polling. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/socket.io?EIO=string&transport=string'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/socket.io?EIO=string&transport=string'
import requests
response = requests.get("http://127.0.0.1:8787/player/socket.io?EIO=string&transport=string")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/socket.io?EIO=string&transport=string");
console.log(response.status, await response.text());
let response = reqwest::get("http://127.0.0.1:8787/player/socket.io?EIO=string&transport=string").await?;
println!("{} {}", response.status(), response.text().await?);
The signed-in patron, as at sign-in, without new tokens.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
-
200The patron and settings;
user.tokenis the card's access token. Body:PlayerLoginResponse(application/json)5 fieldsuserUserrequiredThe signed-in patron, with the card's tokens.userDefaultLibraryIdstringrequiredThe library an app opens first: the whole library.serverSettingsServerSettingsrequiredSettings apps read at sign-in.ereaderDevicesarray of objectrequiredE-reader devices: always empty, the API serves no ebooks.SourcestringrequiredHow the server was installed; apps only display it.
- 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 500The library could not be read. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/authorize' \
-X POST \
-H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/authorize' `
-Method Post `
-Headers @{ Authorization = 'Bearer <playerToken>' }
import requests
response = requests.post(
"http://127.0.0.1:8787/player/api/authorize",
headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/authorize", {
method: "POST",
headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/player/api/authorize")
.header("Authorization", "Bearer <playerToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The patron and settings; user.token is the card's access token.
{
"user": {
"id": "li_8f14e45fceea467f",
"username": "riley",
"email": "riley@example.com",
"type": "user",
"token": "eyJhbGciOi...",
"accessToken": "eyJhbGciOi...",
"refreshToken": "eyJhbGciOi...",
"isOldToken": false,
"mediaProgress": [
{
"id": "li_8f14e45fceea467f",
"userId": "42",
"libraryItemId": "li_8f14e45fceea467f",
"episodeId": null,
"mediaItemId": "li_8f14e45fceea467f",
"mediaItemType": "book",
"duration": 36000.0,
"progress": 0.05,
"currentTime": 1830.5,
"isFinished": false,
"hideFromContinueListening": false,
"ebookLocation": null,
"ebookProgress": null,
"lastUpdate": 1763630000000,
"startedAt": 1763620000000,
"finishedAt": null
}
],
"seriesHideFromContinueListening": [],
"bookmarks": [
{
"libraryItemId": "li_8f14e45fceea467f",
"title": "The First",
"time": 1830.0,
"createdAt": 1763600000000
}
],
"isActive": true,
"isLocked": false,
"lastSeen": 1763630000000,
"createdAt": 1763600000000,
"permissions": {
"download": true,
"update": false,
"delete": false,
"upload": false,
"createEreader": false,
"accessAllLibraries": true,
"accessAllTags": true,
"accessExplicitContent": true,
"selectedTagsNotAccessible": false
},
"librariesAccessible": [
"bookclerk-library"
],
"itemTagsSelected": [],
"hasOpenIDLink": false
},
"userDefaultLibraryId": "bookclerk-library",
"serverSettings": {
"id": "li_8f14e45fceea467f",
"version": "2.17.0",
"buildNumber": 1,
"language": "en-us",
"dateFormat": "MM/dd/yyyy",
"timeFormat": "HH:mm",
"sortingIgnorePrefix": true,
"sortingPrefixes": [
"the",
"a"
],
"chromecastEnabled": false,
"homeBookshelfView": 1,
"bookshelfView": 1,
"authActiveAuthMethods": [
"local",
"openid"
],
"authOpenIDButtonText": "Sign in with the library",
"authOpenIDAutoLaunch": false,
"authLoginCustomMessage": "Sign in with a player password from Settings, Account, Player apps.",
"timeZone": "UTC"
},
"ereaderDevices": [],
"Source": "bookclerk"
}
Schema:
{
"type": "object",
"description": "The answer to a sign-in, a token refresh, `POST /api/authorize` and\nthe browser sign-in's callback.",
"required": [
"user",
"userDefaultLibraryId",
"serverSettings",
"ereaderDevices",
"Source"
],
"properties": {
"user": {
"type": "object",
"description": "The signed-in patron, with the card's tokens.",
"required": [
"id",
"username",
"type",
"token",
"isOldToken",
"mediaProgress",
"seriesHideFromContinueListening",
"bookmarks",
"isActive",
"isLocked",
"createdAt",
"permissions",
"librariesAccessible",
"itemTagsSelected",
"hasOpenIDLink"
],
"properties": {
"id": {
"type": "string",
"description": "The patron's portal identity id, as a string.",
"example": "li_8f14e45fceea467f"
},
"username": {
"type": "string",
"description": "The name the patron signs in with.",
"example": "riley"
},
"email": {
"type": [
"string",
"null"
],
"description": "The patron's email address, if the library has one.",
"example": "riley@example.com"
},
"type": {
"type": "string",
"description": "Always `user`: no app is given administrator powers.",
"example": "user"
},
"token": {
"type": "string",
"description": "The access token, for apps that read it from here (older apps\nsend this one as their bearer). Empty where the answer is not a\nsign-in.",
"example": "eyJhbGciOi..."
},
"accessToken": {
"type": [
"string",
"null"
],
"description": "The card's access token, on sign-in and refresh answers only.",
"example": "eyJhbGciOi..."
},
"refreshToken": {
"type": [
"string",
"null"
],
"description": "The card's refresh token, on sign-in and refresh answers only.",
"example": "eyJhbGciOi..."
},
"isOldToken": {
"type": "boolean",
"description": "Always false: tokens are never the old non-expiring kind.",
"example": false
},
"mediaProgress": {
"type": "array",
"items": {
"type": "object",
"description": "The patron's progress on one item.",
"required": [
"id",
"userId",
"libraryItemId",
"mediaItemId",
"mediaItemType",
"duration",
"progress",
"currentTime",
"isFinished",
"hideFromContinueListening",
"lastUpdate",
"startedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The progress id: the item id (one record per patron and item).",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaItemId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"mediaItemType": {
"type": "string",
"description": "Always `book`.",
"example": "book"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds, as last reported.",
"example": 36000.0
},
"progress": {
"type": "number",
"format": "double",
"description": "The share listened, from 0 to 1.",
"example": 0.05
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished it.",
"example": false
},
"hideFromContinueListening": {
"type": "boolean",
"description": "Whether it is hidden from continue listening.",
"example": false
},
"ebookLocation": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"ebookProgress": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Always null.",
"example": null
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When the progress last changed, in epoch milliseconds.",
"example": 1763630000000
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the patron started, in epoch milliseconds.",
"example": 1763620000000
},
"finishedAt": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron finished, in epoch milliseconds.",
"example": null
}
}
},
"description": "Progress on every item the patron has started."
},
"seriesHideFromContinueListening": {
"type": "array",
"items": {
"type": "string"
},
"description": "Series hidden from continue listening: none.",
"example": []
},
"bookmarks": {
"type": "array",
"items": {
"type": "object",
"description": "A bookmark.",
"required": [
"libraryItemId",
"title",
"time",
"createdAt"
],
"properties": {
"libraryItemId": {
"type": "string",
"description": "The item it is in.",
"example": "li_8f14e45fceea467f"
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
},
"time": {
"type": "number",
"format": "double",
"description": "Where it is, in seconds.",
"example": 1830.0
},
"createdAt": {
"type": "integer",
"format": "int64",
"description": "When it was made, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"description": "Every bookmark the patron has made."
},
"isActive": {
"type": "boolean",
"description": "Always true: a disabled patron cannot sign in.",
"example": true
},
"isLocked": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"lastSeen": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron was last seen, in epoch milliseconds.",
"example": 1763630000000
},
"createdAt": {
"type": "integer",
"format": "int64",
"description": "When the patron joined, in epoch milliseconds.",
"example": 1763600000000
},
"permissions": {
"type": "object",
"description": "What the patron may do.",
"required": [
"download",
"update",
"delete",
"upload",
"createEreader",
"accessAllLibraries",
"accessAllTags",
"accessExplicitContent",
"selectedTagsNotAccessible"
],
"properties": {
"download": {
"type": "boolean",
"description": "Whether the patron may download items to the device.",
"example": true
},
"update": {
"type": "boolean",
"description": "Always false: apps edit nothing.",
"example": false
},
"delete": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"upload": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"createEreader": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"accessAllLibraries": {
"type": "boolean",
"description": "Always true: the libraries listed are the ones the patron sees.",
"example": true
},
"accessAllTags": {
"type": "boolean",
"description": "Always true.",
"example": true
},
"accessExplicitContent": {
"type": "boolean",
"description": "Always true: scope, not an explicit flag, decides visibility.",
"example": true
},
"selectedTagsNotAccessible": {
"type": "boolean",
"description": "Always false.",
"example": false
}
}
},
"librariesAccessible": {
"type": "array",
"items": {
"type": "string"
},
"description": "Libraries the patron may open, by id.",
"example": [
"bookclerk-library"
]
},
"itemTagsSelected": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags that limit what the patron sees: none (scope is applied by\nthe host, not by tags).",
"example": []
},
"hasOpenIDLink": {
"type": "boolean",
"description": "Whether the patron signed in through the browser at least once.",
"example": false
}
}
},
"userDefaultLibraryId": {
"type": "string",
"description": "The library an app opens first: the whole library.",
"example": "bookclerk-library"
},
"serverSettings": {
"type": "object",
"description": "Settings apps read at sign-in.",
"required": [
"id",
"version",
"buildNumber",
"language",
"dateFormat",
"timeFormat",
"sortingIgnorePrefix",
"sortingPrefixes",
"chromecastEnabled",
"homeBookshelfView",
"bookshelfView",
"authActiveAuthMethods",
"authOpenIDButtonText",
"authOpenIDAutoLaunch",
"timeZone"
],
"properties": {
"id": {
"type": "string",
"description": "Always `server-settings`.",
"example": "li_8f14e45fceea467f"
},
"version": {
"type": "string",
"description": "[`crate::COMPATIBLE_SERVER_VERSION`]: apps turn features on by it.",
"example": "2.17.0"
},
"buildNumber": {
"type": "integer",
"format": "int32",
"description": "Always 1.",
"example": 1,
"minimum": 0
},
"language": {
"type": "string",
"description": "The interface language.",
"example": "en-us"
},
"dateFormat": {
"type": "string",
"description": "How apps format dates.",
"example": "MM/dd/yyyy"
},
"timeFormat": {
"type": "string",
"description": "How apps format times.",
"example": "HH:mm"
},
"sortingIgnorePrefix": {
"type": "boolean",
"description": "Whether sorting skips leading articles: no.",
"example": true
},
"sortingPrefixes": {
"type": "array",
"items": {
"type": "string"
},
"description": "The articles sorting would skip.",
"example": [
"the",
"a"
]
},
"chromecastEnabled": {
"type": "boolean",
"description": "Whether apps offer casting: no.",
"example": false
},
"homeBookshelfView": {
"type": "integer",
"format": "int32",
"description": "The home shelf style (1: standard).",
"example": 1,
"minimum": 0
},
"bookshelfView": {
"type": "integer",
"format": "int32",
"description": "The library shelf style (1: standard).",
"example": 1,
"minimum": 0
},
"authActiveAuthMethods": {
"type": "array",
"items": {
"type": "string"
},
"description": "[`AUTH_METHODS`].",
"example": [
"local",
"openid"
]
},
"authOpenIDButtonText": {
"type": "string",
"description": "The browser sign-in button's label.",
"example": "Sign in with the library"
},
"authOpenIDAutoLaunch": {
"type": "boolean",
"description": "Never true.",
"example": false
},
"authLoginCustomMessage": {
"type": [
"string",
"null"
],
"description": "The sign-in screen's note.",
"example": "Sign in with a player password from Settings, Account, Player apps."
},
"timeZone": {
"type": "string",
"description": "The host's time zone name, or UTC.",
"example": "UTC"
}
}
},
"ereaderDevices": {
"type": "array",
"items": {
"type": "object"
},
"description": "E-reader devices: always empty, the API serves no ebooks.",
"example": []
},
"Source": {
"type": "string",
"description": "How the server was installed; apps only display it.",
"example": "bookclerk"
}
}
}
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 500: The library could not be read.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
The signed-in patron.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
-
200The patron, their progress and bookmarks. Body:
User(application/json)19 fieldsidstringrequiredThe patron's portal identity id, as a string.usernamestringrequiredThe name the patron signs in with.emailstring or nullThe patron's email address, if the library has one.typestringrequiredAlwaysuser: no app is given administrator powers.tokenstringrequiredThe access token, for apps that read it from here (older apps send this one as their bearer). Empty where the answer is not a sign-in.accessTokenstring or nullThe card's access token, on sign-in and refresh answers only.refreshTokenstring or nullThe card's refresh token, on sign-in and refresh answers only.isOldTokenbooleanrequiredAlways false: tokens are never the old non-expiring kind.mediaProgressarray ofMediaProgressrequiredProgress on every item the patron has started.seriesHideFromContinueListeningarray of stringrequiredSeries hidden from continue listening: none.bookmarksarray ofBookmarkrequiredEvery bookmark the patron has made.isActivebooleanrequiredAlways true: a disabled patron cannot sign in.isLockedbooleanrequiredAlways false.lastSeeninteger (int64) or nullWhen the patron was last seen, in epoch milliseconds.createdAtinteger (int64)requiredWhen the patron joined, in epoch milliseconds.permissionsPermissionsrequiredWhat the patron may do.librariesAccessiblearray of stringrequiredLibraries the patron may open, by id.itemTagsSelectedarray of stringrequiredTags that limit what the patron sees: none (scope is applied by the host, not by tags).hasOpenIDLinkbooleanrequiredWhether the patron signed in through the browser at least once.
- 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 500The library could not be read. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/me' \
-H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/me' `
-Headers @{ Authorization = 'Bearer <playerToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/player/api/me",
headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/me", {
headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/player/api/me")
.header("Authorization", "Bearer <playerToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The patron, their progress and bookmarks.
{
"id": "li_8f14e45fceea467f",
"username": "riley",
"email": "riley@example.com",
"type": "user",
"token": "eyJhbGciOi...",
"accessToken": "eyJhbGciOi...",
"refreshToken": "eyJhbGciOi...",
"isOldToken": false,
"mediaProgress": [
{
"id": "li_8f14e45fceea467f",
"userId": "42",
"libraryItemId": "li_8f14e45fceea467f",
"episodeId": null,
"mediaItemId": "li_8f14e45fceea467f",
"mediaItemType": "book",
"duration": 36000.0,
"progress": 0.05,
"currentTime": 1830.5,
"isFinished": false,
"hideFromContinueListening": false,
"ebookLocation": null,
"ebookProgress": null,
"lastUpdate": 1763630000000,
"startedAt": 1763620000000,
"finishedAt": null
}
],
"seriesHideFromContinueListening": [],
"bookmarks": [
{
"libraryItemId": "li_8f14e45fceea467f",
"title": "The First",
"time": 1830.0,
"createdAt": 1763600000000
}
],
"isActive": true,
"isLocked": false,
"lastSeen": 1763630000000,
"createdAt": 1763600000000,
"permissions": {
"download": true,
"update": false,
"delete": false,
"upload": false,
"createEreader": false,
"accessAllLibraries": true,
"accessAllTags": true,
"accessExplicitContent": true,
"selectedTagsNotAccessible": false
},
"librariesAccessible": [
"bookclerk-library"
],
"itemTagsSelected": [],
"hasOpenIDLink": false
}
Schema:
{
"type": "object",
"description": "A patron as apps see them.",
"required": [
"id",
"username",
"type",
"token",
"isOldToken",
"mediaProgress",
"seriesHideFromContinueListening",
"bookmarks",
"isActive",
"isLocked",
"createdAt",
"permissions",
"librariesAccessible",
"itemTagsSelected",
"hasOpenIDLink"
],
"properties": {
"id": {
"type": "string",
"description": "The patron's portal identity id, as a string.",
"example": "li_8f14e45fceea467f"
},
"username": {
"type": "string",
"description": "The name the patron signs in with.",
"example": "riley"
},
"email": {
"type": [
"string",
"null"
],
"description": "The patron's email address, if the library has one.",
"example": "riley@example.com"
},
"type": {
"type": "string",
"description": "Always `user`: no app is given administrator powers.",
"example": "user"
},
"token": {
"type": "string",
"description": "The access token, for apps that read it from here (older apps\nsend this one as their bearer). Empty where the answer is not a\nsign-in.",
"example": "eyJhbGciOi..."
},
"accessToken": {
"type": [
"string",
"null"
],
"description": "The card's access token, on sign-in and refresh answers only.",
"example": "eyJhbGciOi..."
},
"refreshToken": {
"type": [
"string",
"null"
],
"description": "The card's refresh token, on sign-in and refresh answers only.",
"example": "eyJhbGciOi..."
},
"isOldToken": {
"type": "boolean",
"description": "Always false: tokens are never the old non-expiring kind.",
"example": false
},
"mediaProgress": {
"type": "array",
"items": {
"type": "object",
"description": "The patron's progress on one item.",
"required": [
"id",
"userId",
"libraryItemId",
"mediaItemId",
"mediaItemType",
"duration",
"progress",
"currentTime",
"isFinished",
"hideFromContinueListening",
"lastUpdate",
"startedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The progress id: the item id (one record per patron and item).",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaItemId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"mediaItemType": {
"type": "string",
"description": "Always `book`.",
"example": "book"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds, as last reported.",
"example": 36000.0
},
"progress": {
"type": "number",
"format": "double",
"description": "The share listened, from 0 to 1.",
"example": 0.05
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished it.",
"example": false
},
"hideFromContinueListening": {
"type": "boolean",
"description": "Whether it is hidden from continue listening.",
"example": false
},
"ebookLocation": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"ebookProgress": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Always null.",
"example": null
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When the progress last changed, in epoch milliseconds.",
"example": 1763630000000
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the patron started, in epoch milliseconds.",
"example": 1763620000000
},
"finishedAt": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron finished, in epoch milliseconds.",
"example": null
}
}
},
"description": "Progress on every item the patron has started."
},
"seriesHideFromContinueListening": {
"type": "array",
"items": {
"type": "string"
},
"description": "Series hidden from continue listening: none.",
"example": []
},
"bookmarks": {
"type": "array",
"items": {
"type": "object",
"description": "A bookmark.",
"required": [
"libraryItemId",
"title",
"time",
"createdAt"
],
"properties": {
"libraryItemId": {
"type": "string",
"description": "The item it is in.",
"example": "li_8f14e45fceea467f"
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
},
"time": {
"type": "number",
"format": "double",
"description": "Where it is, in seconds.",
"example": 1830.0
},
"createdAt": {
"type": "integer",
"format": "int64",
"description": "When it was made, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"description": "Every bookmark the patron has made."
},
"isActive": {
"type": "boolean",
"description": "Always true: a disabled patron cannot sign in.",
"example": true
},
"isLocked": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"lastSeen": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron was last seen, in epoch milliseconds.",
"example": 1763630000000
},
"createdAt": {
"type": "integer",
"format": "int64",
"description": "When the patron joined, in epoch milliseconds.",
"example": 1763600000000
},
"permissions": {
"type": "object",
"description": "What the patron may do.",
"required": [
"download",
"update",
"delete",
"upload",
"createEreader",
"accessAllLibraries",
"accessAllTags",
"accessExplicitContent",
"selectedTagsNotAccessible"
],
"properties": {
"download": {
"type": "boolean",
"description": "Whether the patron may download items to the device.",
"example": true
},
"update": {
"type": "boolean",
"description": "Always false: apps edit nothing.",
"example": false
},
"delete": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"upload": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"createEreader": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"accessAllLibraries": {
"type": "boolean",
"description": "Always true: the libraries listed are the ones the patron sees.",
"example": true
},
"accessAllTags": {
"type": "boolean",
"description": "Always true.",
"example": true
},
"accessExplicitContent": {
"type": "boolean",
"description": "Always true: scope, not an explicit flag, decides visibility.",
"example": true
},
"selectedTagsNotAccessible": {
"type": "boolean",
"description": "Always false.",
"example": false
}
}
},
"librariesAccessible": {
"type": "array",
"items": {
"type": "string"
},
"description": "Libraries the patron may open, by id.",
"example": [
"bookclerk-library"
]
},
"itemTagsSelected": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags that limit what the patron sees: none (scope is applied by\nthe host, not by tags).",
"example": []
},
"hasOpenIDLink": {
"type": "boolean",
"description": "Whether the patron signed in through the browser at least once.",
"example": false
}
}
}
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 500: The library could not be read.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Lists the libraries the patron may open: the one library.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
- 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/libraries' \
-H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/libraries' `
-Headers @{ Authorization = 'Bearer <playerToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/player/api/libraries",
headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/libraries", {
headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/player/api/libraries")
.header("Authorization", "Bearer <playerToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The library.
{
"libraries": [
{
"id": "li_8f14e45fceea467f",
"name": "Ann Author",
"folders": [],
"displayOrder": 1,
"icon": "audiobookshelf",
"mediaType": "book",
"provider": "audible",
"settings": {
"coverAspectRatio": 1,
"disableWatcher": false,
"audiobooksOnly": true,
"hideSingleBookSeries": false,
"onlyShowLaterBooksInContinueSeries": false,
"epubsAllowScriptedContent": false,
"markAsFinishedPercentComplete": null,
"markAsFinishedTimeRemaining": 10
},
"lastScan": null,
"lastScanVersion": "2.17.0",
"createdAt": 1763600000000,
"lastUpdate": 1763630000000
}
]
}
Schema:
{
"type": "object",
"description": "`GET /api/libraries`.",
"required": [
"libraries"
],
"properties": {
"libraries": {
"type": "array",
"items": {
"type": "object",
"description": "One library an app can open.",
"required": [
"id",
"name",
"folders",
"displayOrder",
"icon",
"mediaType",
"provider",
"settings",
"createdAt",
"lastUpdate"
],
"properties": {
"id": {
"type": "string",
"description": "The library id ([`crate::ids::WHOLE_LIBRARY_ID`] for the whole\nlibrary).",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The library's name.",
"example": "Ann Author"
},
"folders": {
"type": "array",
"items": {
"type": "object"
},
"description": "Folders on disk: none are shown.",
"example": []
},
"displayOrder": {
"type": "integer",
"format": "int32",
"description": "The library's place in the list, from 1.",
"example": 1,
"minimum": 0
},
"icon": {
"type": "string",
"description": "The icon apps show (`audiobookshelf` names a book stack).",
"example": "audiobookshelf"
},
"mediaType": {
"type": "string",
"description": "Always [`MEDIA_TYPE_BOOK`].",
"example": "book"
},
"provider": {
"type": "string",
"description": "The metadata provider apps show: none.",
"example": "audible"
},
"settings": {
"type": "object",
"description": "Display settings.",
"required": [
"coverAspectRatio",
"disableWatcher",
"audiobooksOnly",
"hideSingleBookSeries",
"onlyShowLaterBooksInContinueSeries",
"epubsAllowScriptedContent",
"markAsFinishedTimeRemaining"
],
"properties": {
"coverAspectRatio": {
"type": "integer",
"format": "int32",
"description": "1 for square covers, 2 for the 1.6:1 book shape: square.",
"example": 1,
"minimum": 0
},
"disableWatcher": {
"type": "boolean",
"description": "Always true: the library is not a watched folder.",
"example": false
},
"audiobooksOnly": {
"type": "boolean",
"description": "Always true: audiobooks only.",
"example": true
},
"hideSingleBookSeries": {
"type": "boolean",
"description": "Whether one-book series are hidden from the series list: no.",
"example": false
},
"onlyShowLaterBooksInContinueSeries": {
"type": "boolean",
"description": "Whether continue series skips earlier books: no.",
"example": false
},
"epubsAllowScriptedContent": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"markAsFinishedPercentComplete": {
"type": [
"number",
"null"
],
"format": "double",
"description": "An item counts as finished at this share listened, in percent.",
"example": null
},
"markAsFinishedTimeRemaining": {
"type": "number",
"format": "double",
"description": "An item counts as finished with this many seconds left.",
"example": 10
}
}
},
"lastScan": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Always null.",
"example": null
},
"lastScanVersion": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": "2.17.0"
},
"createdAt": {
"type": "integer",
"format": "int64",
"description": "When the library was made, in epoch milliseconds.",
"example": 1763600000000
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When it last changed, in epoch milliseconds.",
"example": 1763630000000
}
}
},
"description": "The libraries the patron may open."
}
}
}
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Reads the library.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
idpathstringrequiredLibrary id.includequerystringfilterdatato add the filter values.
- 200The library. Body:
LibraryAnswer(application/json) - 400A query value is out of range. Body: string (
text/plain) - 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 404No such library. Body: string (
text/plain) - 500The library could not be read. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/libraries/<id>' \
-H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/libraries/<id>' `
-Headers @{ Authorization = 'Bearer <playerToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/player/api/libraries/<id>",
headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/libraries/<id>", {
headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/player/api/libraries/<id>")
.header("Authorization", "Bearer <playerToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The library.
{
"filterdata": {
"authors": [
{
"id": "li_8f14e45fceea467f",
"name": "Ann Author"
}
],
"genres": [
"Fantasy"
],
"tags": [],
"series": [
{
"id": "li_8f14e45fceea467f",
"name": "Ann Author"
}
],
"narrators": [
"Nia Narrator"
],
"languages": [
"en-us"
],
"publishers": [
"Example Press"
],
"publishedDecades": [
"2020"
],
"bookCount": 1,
"authorCount": 1,
"seriesCount": 1,
"podcastCount": 0,
"numberEpisodes": 0,
"loadedAt": 1763630000000
},
"issues": 0,
"numUserPlaylists": 0,
"library": {
"id": "li_8f14e45fceea467f",
"name": "Ann Author",
"folders": [],
"displayOrder": 1,
"icon": "audiobookshelf",
"mediaType": "book",
"provider": "audible",
"settings": {
"coverAspectRatio": 1,
"disableWatcher": false,
"audiobooksOnly": true,
"hideSingleBookSeries": false,
"onlyShowLaterBooksInContinueSeries": false,
"epubsAllowScriptedContent": false,
"markAsFinishedPercentComplete": null,
"markAsFinishedTimeRemaining": 10
},
"lastScan": null,
"lastScanVersion": "2.17.0",
"createdAt": 1763600000000,
"lastUpdate": 1763630000000
}
}
Schema:
{
"oneOf": [
{
"type": "object",
"description": "With `include=filterdata`.",
"required": [
"filterdata",
"issues",
"numUserPlaylists",
"library"
],
"properties": {
"filterdata": {
"type": "object",
"description": "The filter values.",
"required": [
"authors",
"genres",
"tags",
"series",
"narrators",
"languages",
"publishers",
"publishedDecades",
"bookCount",
"authorCount",
"seriesCount",
"podcastCount",
"numberEpisodes",
"loadedAt"
],
"properties": {
"authors": {
"type": "array",
"items": {
"type": "object",
"description": "An id and a name.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its display name.",
"example": "Ann Author"
}
}
},
"description": "Authors with at least one item."
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"description": "Genres.",
"example": [
"Fantasy"
]
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags: none are shown.",
"example": []
},
"series": {
"type": "array",
"items": {
"type": "object",
"description": "An id and a name.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its display name.",
"example": "Ann Author"
}
}
},
"description": "Series with at least one item."
},
"narrators": {
"type": "array",
"items": {
"type": "string"
},
"description": "Narrators.",
"example": [
"Nia Narrator"
]
},
"languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Languages.",
"example": [
"en-us"
]
},
"publishers": {
"type": "array",
"items": {
"type": "string"
},
"description": "Publishers.",
"example": [
"Example Press"
]
},
"publishedDecades": {
"type": "array",
"items": {
"type": "string"
},
"description": "Decades of publication: none are offered.",
"example": [
"2020"
]
},
"bookCount": {
"type": "integer",
"format": "int64",
"description": "Items in the library.",
"example": 1,
"minimum": 0
},
"authorCount": {
"type": "integer",
"format": "int64",
"description": "Authors in the library.",
"example": 1,
"minimum": 0
},
"seriesCount": {
"type": "integer",
"format": "int64",
"description": "Series in the library.",
"example": 1,
"minimum": 0
},
"podcastCount": {
"type": "integer",
"format": "int64",
"description": "Always 0.",
"example": 0,
"minimum": 0
},
"numberEpisodes": {
"type": "integer",
"format": "int64",
"description": "Always 0.",
"example": 0,
"minimum": 0
},
"loadedAt": {
"type": "integer",
"format": "int64",
"description": "When the values were read, in epoch milliseconds.",
"example": 1763630000000
}
}
},
"issues": {
"type": "integer",
"format": "int64",
"description": "Items with problems: none are reported.",
"example": 0,
"minimum": 0
},
"numUserPlaylists": {
"type": "integer",
"format": "int64",
"description": "The patron's playlists in the library: none.",
"example": 0,
"minimum": 0
},
"library": {
"type": "object",
"description": "The library.",
"required": [
"id",
"name",
"folders",
"displayOrder",
"icon",
"mediaType",
"provider",
"settings",
"createdAt",
"lastUpdate"
],
"properties": {
"id": {
"type": "string",
"description": "The library id ([`crate::ids::WHOLE_LIBRARY_ID`] for the whole\nlibrary).",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The library's name.",
"example": "Ann Author"
},
"folders": {
"type": "array",
"items": {
"type": "object"
},
"description": "Folders on disk: none are shown.",
"example": []
},
"displayOrder": {
"type": "integer",
"format": "int32",
"description": "The library's place in the list, from 1.",
"example": 1,
"minimum": 0
},
"icon": {
"type": "string",
"description": "The icon apps show (`audiobookshelf` names a book stack).",
"example": "audiobookshelf"
},
"mediaType": {
"type": "string",
"description": "Always [`MEDIA_TYPE_BOOK`].",
"example": "book"
},
"provider": {
"type": "string",
"description": "The metadata provider apps show: none.",
"example": "audible"
},
"settings": {
"type": "object",
"description": "Display settings.",
"required": [
"coverAspectRatio",
"disableWatcher",
"audiobooksOnly",
"hideSingleBookSeries",
"onlyShowLaterBooksInContinueSeries",
"epubsAllowScriptedContent",
"markAsFinishedTimeRemaining"
],
"properties": {
"coverAspectRatio": {
"type": "integer",
"format": "int32",
"description": "1 for square covers, 2 for the 1.6:1 book shape: square.",
"example": 1,
"minimum": 0
},
"disableWatcher": {
"type": "boolean",
"description": "Always true: the library is not a watched folder.",
"example": false
},
"audiobooksOnly": {
"type": "boolean",
"description": "Always true: audiobooks only.",
"example": true
},
"hideSingleBookSeries": {
"type": "boolean",
"description": "Whether one-book series are hidden from the series list: no.",
"example": false
},
"onlyShowLaterBooksInContinueSeries": {
"type": "boolean",
"description": "Whether continue series skips earlier books: no.",
"example": false
},
"epubsAllowScriptedContent": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"markAsFinishedPercentComplete": {
"type": [
"number",
"null"
],
"format": "double",
"description": "An item counts as finished at this share listened, in percent.",
"example": null
},
"markAsFinishedTimeRemaining": {
"type": "number",
"format": "double",
"description": "An item counts as finished with this many seconds left.",
"example": 10
}
}
},
"lastScan": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Always null.",
"example": null
},
"lastScanVersion": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": "2.17.0"
},
"createdAt": {
"type": "integer",
"format": "int64",
"description": "When the library was made, in epoch milliseconds.",
"example": 1763600000000
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When it last changed, in epoch milliseconds.",
"example": 1763630000000
}
}
}
}
},
{
"type": "object",
"description": "Otherwise.",
"required": [
"id",
"name",
"folders",
"displayOrder",
"icon",
"mediaType",
"provider",
"settings",
"createdAt",
"lastUpdate"
],
"properties": {
"id": {
"type": "string",
"description": "The library id ([`crate::ids::WHOLE_LIBRARY_ID`] for the whole\nlibrary).",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The library's name.",
"example": "Ann Author"
},
"folders": {
"type": "array",
"items": {
"type": "object"
},
"description": "Folders on disk: none are shown.",
"example": []
},
"displayOrder": {
"type": "integer",
"format": "int32",
"description": "The library's place in the list, from 1.",
"example": 1,
"minimum": 0
},
"icon": {
"type": "string",
"description": "The icon apps show (`audiobookshelf` names a book stack).",
"example": "audiobookshelf"
},
"mediaType": {
"type": "string",
"description": "Always [`MEDIA_TYPE_BOOK`].",
"example": "book"
},
"provider": {
"type": "string",
"description": "The metadata provider apps show: none.",
"example": "audible"
},
"settings": {
"type": "object",
"description": "Display settings.",
"required": [
"coverAspectRatio",
"disableWatcher",
"audiobooksOnly",
"hideSingleBookSeries",
"onlyShowLaterBooksInContinueSeries",
"epubsAllowScriptedContent",
"markAsFinishedTimeRemaining"
],
"properties": {
"coverAspectRatio": {
"type": "integer",
"format": "int32",
"description": "1 for square covers, 2 for the 1.6:1 book shape: square.",
"example": 1,
"minimum": 0
},
"disableWatcher": {
"type": "boolean",
"description": "Always true: the library is not a watched folder.",
"example": false
},
"audiobooksOnly": {
"type": "boolean",
"description": "Always true: audiobooks only.",
"example": true
},
"hideSingleBookSeries": {
"type": "boolean",
"description": "Whether one-book series are hidden from the series list: no.",
"example": false
},
"onlyShowLaterBooksInContinueSeries": {
"type": "boolean",
"description": "Whether continue series skips earlier books: no.",
"example": false
},
"epubsAllowScriptedContent": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"markAsFinishedPercentComplete": {
"type": [
"number",
"null"
],
"format": "double",
"description": "An item counts as finished at this share listened, in percent.",
"example": null
},
"markAsFinishedTimeRemaining": {
"type": "number",
"format": "double",
"description": "An item counts as finished with this many seconds left.",
"example": 10
}
}
},
"lastScan": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Always null.",
"example": null
},
"lastScanVersion": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": "2.17.0"
},
"createdAt": {
"type": "integer",
"format": "int64",
"description": "When the library was made, in epoch milliseconds.",
"example": 1763600000000
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When it last changed, in epoch milliseconds.",
"example": 1763630000000
}
}
}
],
"description": "`GET /player/api/libraries/{id}` answer: the library, with its filter\nvalues when asked for (`include=filterdata`)."
}
Status 400: A query value is out of range.
Bad Request
Schema:
A text/plain body: a string.
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 404: No such library.
Not Found
Schema:
A text/plain body: a string.
Status 500: The library could not be read.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Lists the library's items, one page at a time.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
idpathstringrequiredLibrary id.limitqueryinteger (int64)Items per page, at most 1000; 0 for all (up to 1000).pagequeryinteger (int64)Page number, from 0.sortquerystringmedia.metadata.title,media.metadata.authorName,addedAt,media.durationorsequence.descqueryinteger (int32)1 to reverse the order.filterquerystringgroup.base64value: authors, series, genres, tags, narrators, publishers or progress.includequerystringprogressto add the patron's progress.minifiedqueryinteger (int32)Accepted; items are always the short shape.
-
200A page of items. Body:
ItemPage(application/json)12 fieldsresultsarray ofLibraryItemrequiredThe page's items.totalinteger (int64)requiredItems matching the query in all. At least 0.limitinteger (int64)requiredItems per page (0: no paging). At least 0.pageinteger (int64)requiredThe page number, from 0. At least 0.sortBystring or nullThe sort key the app sent, echoed.sortDescbooleanrequiredWhether the order is reversed.filterBystring or nullThe filter the app sent, echoed.mediaTypestringrequiredAlways [MEDIA_TYPE_BOOK].minifiedbooleanrequiredWhether items are minified.collapseseriesbooleanrequiredWhether series were collapsed: never.includestringrequiredThe include list the app sent, echoed.offsetinteger (int64)requiredThe offset of the first result. At least 0.
- 400A query value is out of range. Body: string (
text/plain) - 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 404No such library. Body: string (
text/plain) - 500The library could not be read. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/libraries/<id>/items' \
-H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/libraries/<id>/items' `
-Headers @{ Authorization = 'Bearer <playerToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/player/api/libraries/<id>/items",
headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/libraries/<id>/items", {
headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/player/api/libraries/<id>/items")
.header("Authorization", "Bearer <playerToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: A page of items.
{
"results": [
{
"id": "li_8f14e45fceea467f",
"ino": "0",
"oldLibraryItemId": null,
"libraryId": "bookclerk-library",
"folderId": "bookclerk-library",
"path": "/the-first.m4b",
"relPath": "the-first.m4b",
"isFile": true,
"mtimeMs": 1763600000000,
"ctimeMs": 1763600000000,
"birthtimeMs": 1763600000000,
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"isMissing": false,
"isInvalid": false,
"mediaType": "book",
"media": {
"id": "li_8f14e45fceea467f",
"libraryItemId": "li_8f14e45fceea467f",
"metadata": {
"title": "The First",
"titleIgnorePrefix": "First, The",
"authors": [],
"authorName": "Ann Author",
"authorNameLF": "Author, Ann",
"narrators": [
"Nia Narrator"
],
"narratorName": "Nia Narrator",
"series": [],
"seriesName": "The Saga #1",
"genres": [
"Fantasy"
],
"explicit": false,
"abridged": false
},
"coverPath": "/player/api/items/li_8f14e45fceea467f/cover",
"tags": [],
"numTracks": 1,
"numAudioFiles": 1,
"numChapters": 0,
"duration": 36000.0,
"size": 100000,
"audioFiles": [],
"chapters": [],
"tracks": []
},
"numFiles": 1,
"size": 100000,
"libraryFiles": [
{
"ino": "0",
"metadata": {
"filename": "the-first.m4b",
"ext": ".m4b",
"path": "/the-first.m4b",
"relPath": "the-first.m4b",
"size": 100000,
"mtimeMs": 1763600000000,
"ctimeMs": 1763600000000,
"birthtimeMs": 1763600000000
},
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"fileType": "audio"
}
],
"userMediaProgress": {
"id": "li_8f14e45fceea467f",
"userId": "42",
"libraryItemId": "li_8f14e45fceea467f",
"episodeId": null,
"mediaItemId": "li_8f14e45fceea467f",
"mediaItemType": "book",
"duration": 36000.0,
"progress": 0.05,
"currentTime": 1830.5,
"isFinished": false,
"hideFromContinueListening": false,
"ebookLocation": null,
"ebookProgress": null,
"lastUpdate": 1763630000000,
"startedAt": 1763620000000,
"finishedAt": null
},
"seriesSequence": "1"
}
],
"total": 1,
"limit": 20,
"page": 0,
"sortBy": "media.metadata.title",
"sortDesc": false,
"filterBy": null,
"mediaType": "book",
"minified": false,
"collapseseries": false,
"include": "",
"offset": 0
}
Schema:
{
"type": "object",
"description": "A page of items: `GET /api/libraries/{id}/items` and the like.",
"required": [
"results",
"total",
"limit",
"page",
"sortDesc",
"mediaType",
"minified",
"collapseseries",
"include",
"offset"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"description": "An item: an edition with a stored copy.",
"required": [
"id",
"ino",
"libraryId",
"folderId",
"path",
"relPath",
"isFile",
"mtimeMs",
"ctimeMs",
"birthtimeMs",
"addedAt",
"updatedAt",
"isMissing",
"isInvalid",
"mediaType",
"media",
"numFiles",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The item id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"ino": {
"type": "string",
"description": "The item's inode as apps expect one: the edition id again.",
"example": "0"
},
"oldLibraryItemId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"libraryId": {
"type": "string",
"description": "The library the item is listed in.",
"example": "bookclerk-library"
},
"folderId": {
"type": "string",
"description": "The folder id: the library id.",
"example": "bookclerk-library"
},
"path": {
"type": "string",
"description": "A display path: the title.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the title.",
"example": "the-first.m4b"
},
"isFile": {
"type": "boolean",
"description": "Always false: an item is a folder of tracks.",
"example": true
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy last changed, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the item joined the library, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When its record last changed, in epoch milliseconds.",
"example": 1763630000000
},
"isMissing": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"isInvalid": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"mediaType": {
"type": "string",
"description": "Always [`MEDIA_TYPE_BOOK`].",
"example": "book"
},
"media": {
"type": "object",
"description": "The book.",
"required": [
"id",
"metadata",
"tags",
"numTracks",
"numAudioFiles",
"numChapters",
"duration",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The media id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"libraryItemId": {
"type": [
"string",
"null"
],
"description": "The item id, when fetched expanded.",
"example": "li_8f14e45fceea467f"
},
"metadata": {
"type": "object",
"description": "The book's metadata.",
"required": [
"title",
"titleIgnorePrefix",
"authors",
"authorName",
"authorNameLF",
"narrators",
"narratorName",
"series",
"seriesName",
"genres",
"explicit",
"abridged"
],
"properties": {
"title": {
"type": "string",
"description": "The title.",
"example": "The First"
},
"titleIgnorePrefix": {
"type": "string",
"description": "The title for sorting.",
"example": "First, The"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "The subtitle, if any.",
"example": "A Novel"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"description": "An id and a name.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its display name.",
"example": "Ann Author"
}
}
},
"description": "The authors."
},
"authorName": {
"type": "string",
"description": "The authors' names joined with `, `.",
"example": "Ann Author"
},
"authorNameLF": {
"type": "string",
"description": "The authors' names, family name first, joined with `, `.",
"example": "Author, Ann"
},
"narrators": {
"type": "array",
"items": {
"type": "string"
},
"description": "The narrators' names.",
"example": [
"Nia Narrator"
]
},
"narratorName": {
"type": "string",
"description": "The narrators' names joined with `, `.",
"example": "Nia Narrator"
},
"series": {
"type": "array",
"items": {
"type": "object",
"description": "A series an item belongs to, with the item's place in it.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The series name.",
"example": "Ann Author"
},
"sequence": {
"type": [
"string",
"null"
],
"description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
"example": "1"
}
}
},
"description": "The series the book is in."
},
"seriesName": {
"type": "string",
"description": "The series names with the book's place (`Name #2`), joined.",
"example": "The Saga #1"
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"description": "Genres.",
"example": [
"Fantasy"
]
},
"publishedYear": {
"type": [
"string",
"null"
],
"description": "The year of publication, as a string (`\"2019\"`).",
"example": "2024"
},
"publishedDate": {
"type": [
"string",
"null"
],
"description": "The date of publication, if known.",
"example": "2024-03-01"
},
"publisher": {
"type": [
"string",
"null"
],
"description": "The publisher.",
"example": "Example Press"
},
"description": {
"type": [
"string",
"null"
],
"description": "The description, as the library stores it.",
"example": "A short description."
},
"descriptionPlain": {
"type": [
"string",
"null"
],
"description": "The description with markup removed.",
"example": "A short description."
},
"isbn": {
"type": [
"string",
"null"
],
"description": "The ISBN, if known.",
"example": "9780000000002"
},
"asin": {
"type": [
"string",
"null"
],
"description": "The ASIN, if known.",
"example": "B000000000"
},
"language": {
"type": [
"string",
"null"
],
"description": "The language.",
"example": "en-us"
},
"explicit": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"abridged": {
"type": "boolean",
"description": "Whether the edition is abridged.",
"example": false
}
}
},
"coverPath": {
"type": [
"string",
"null"
],
"description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
"example": "/player/api/items/li_8f14e45fceea467f/cover"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags: none.",
"example": []
},
"numTracks": {
"type": "integer",
"format": "int64",
"description": "Tracks in play order.",
"example": 1,
"minimum": 0
},
"numAudioFiles": {
"type": "integer",
"format": "int64",
"description": "Audio files.",
"example": 1,
"minimum": 0
},
"numChapters": {
"type": "integer",
"format": "int64",
"description": "Chapters.",
"example": 0,
"minimum": 0
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds.",
"example": 36000.0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in its audio files.",
"example": 100000,
"minimum": 0
},
"audioFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "An audio file of a book.",
"required": [
"index",
"ino",
"metadata",
"addedAt",
"updatedAt",
"manuallyVerified",
"exclude",
"duration",
"chapters",
"metaTags",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The file's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"trackNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number the file's tags state: not read.",
"example": 1,
"minimum": 0
},
"discNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number the file's tags state: not read.",
"example": null,
"minimum": 0
},
"trackNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number in the file name: not read.",
"example": null,
"minimum": 0
},
"discNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number in the file name: not read.",
"example": null,
"minimum": 0
},
"manuallyVerified": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"exclude": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"error": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"format": {
"type": [
"string",
"null"
],
"description": "The container format, such as `mp4` or `mp3`.",
"example": "MP4A"
},
"duration": {
"type": "number",
"format": "double",
"description": "The file's length in seconds.",
"example": 36000.0
},
"bitRate": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Bits per second, if known.",
"example": 128000,
"minimum": 0
},
"language": {
"type": [
"string",
"null"
],
"description": "The file's language, if known.",
"example": "en-us"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"timeBase": {
"type": [
"string",
"null"
],
"description": "The time base, if known.",
"example": "1/44100"
},
"channels": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Audio channels, if known.",
"example": 2,
"minimum": 0
},
"channelLayout": {
"type": [
"string",
"null"
],
"description": "The channel layout, if known.",
"example": "stereo"
},
"chapters": {
"type": "array",
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "Chapters embedded in the file: none are read."
},
"embeddedCoverArt": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"metaTags": {
"type": "object",
"description": "Tags read from the file: none until the stored media probe reads\nthem."
},
"mimeType": {
"type": "string",
"description": "The file's media type, such as `audio/mp4`.",
"example": "audio/mp4"
}
}
},
"description": "The audio files, when fetched expanded."
},
"chapters": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "The chapters, when fetched expanded."
},
"tracks": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A track with its place in the book.",
"required": [
"index",
"startOffset",
"duration",
"title",
"contentUrl",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The track's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"startOffset": {
"type": "number",
"format": "double",
"description": "Where the track starts in the book, in seconds.",
"example": 0.0
},
"duration": {
"type": "number",
"format": "double",
"description": "The track's length in seconds.",
"example": 36000.0
},
"title": {
"type": "string",
"description": "The track's title: its file name.",
"example": "The First"
},
"contentUrl": {
"type": "string",
"description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
"example": "/player/api/items/li_8f14e45fceea467f/file/0"
},
"mimeType": {
"type": "string",
"description": "The track's media type.",
"example": "audio/mp4"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"metadata": {
"oneOf": [
{
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "The tracks with their place in the book, when fetched expanded."
}
}
},
"numFiles": {
"type": "integer",
"format": "int64",
"description": "Files in the item.",
"example": 1,
"minimum": 0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in all its files.",
"example": 100000,
"minimum": 0
},
"libraryFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A file of an item, in the expanded item's `libraryFiles`.",
"required": [
"ino",
"metadata",
"addedAt",
"updatedAt",
"fileType"
],
"properties": {
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"fileType": {
"type": "string",
"description": "Always `audio`.",
"example": "audio"
}
}
},
"description": "The item's files, when the item is fetched expanded."
},
"userMediaProgress": {
"oneOf": [
{
"type": "object",
"description": "The patron's progress, when the app asked for it.",
"required": [
"id",
"userId",
"libraryItemId",
"mediaItemId",
"mediaItemType",
"duration",
"progress",
"currentTime",
"isFinished",
"hideFromContinueListening",
"lastUpdate",
"startedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The progress id: the item id (one record per patron and item).",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaItemId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"mediaItemType": {
"type": "string",
"description": "Always `book`.",
"example": "book"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds, as last reported.",
"example": 36000.0
},
"progress": {
"type": "number",
"format": "double",
"description": "The share listened, from 0 to 1.",
"example": 0.05
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished it.",
"example": false
},
"hideFromContinueListening": {
"type": "boolean",
"description": "Whether it is hidden from continue listening.",
"example": false
},
"ebookLocation": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"ebookProgress": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Always null.",
"example": null
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When the progress last changed, in epoch milliseconds.",
"example": 1763630000000
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the patron started, in epoch milliseconds.",
"example": 1763620000000
},
"finishedAt": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron finished, in epoch milliseconds.",
"example": null
}
}
},
{
"type": "null"
}
]
},
"seriesSequence": {
"type": [
"string",
"null"
],
"description": "The item's place in a series, on a series' book list.",
"example": "1"
}
}
},
"description": "The page's items."
},
"total": {
"type": "integer",
"format": "int64",
"description": "Items matching the query in all.",
"example": 1,
"minimum": 0
},
"limit": {
"type": "integer",
"format": "int64",
"description": "Items per page (0: no paging).",
"example": 20,
"minimum": 0
},
"page": {
"type": "integer",
"format": "int64",
"description": "The page number, from 0.",
"example": 0,
"minimum": 0
},
"sortBy": {
"type": [
"string",
"null"
],
"description": "The sort key the app sent, echoed.",
"example": "media.metadata.title"
},
"sortDesc": {
"type": "boolean",
"description": "Whether the order is reversed.",
"example": false
},
"filterBy": {
"type": [
"string",
"null"
],
"description": "The filter the app sent, echoed.",
"example": null
},
"mediaType": {
"type": "string",
"description": "Always [`MEDIA_TYPE_BOOK`].",
"example": "book"
},
"minified": {
"type": "boolean",
"description": "Whether items are minified.",
"example": false
},
"collapseseries": {
"type": "boolean",
"description": "Whether series were collapsed: never.",
"example": false
},
"include": {
"type": "string",
"description": "The include list the app sent, echoed.",
"example": ""
},
"offset": {
"type": "integer",
"format": "int64",
"description": "The offset of the first result.",
"example": 0,
"minimum": 0
}
}
}
Status 400: A query value is out of range.
Bad Request
Schema:
A text/plain body: a string.
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 404: No such library.
Not Found
Schema:
A text/plain body: a string.
Status 500: The library could not be read.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Lists the library's series, one page at a time.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
idpathstringrequiredLibrary id.limitqueryinteger (int64)Series per page; 0 for all (up to 1000).pagequeryinteger (int64)Page number, from 0.descqueryinteger (int32)1 for Z to A.
-
200A page of series, each with its items. Body:
SeriesPage(application/json)9 fieldsresultsarray ofSeriesrequiredThe page's series.totalinteger (int64)requiredSeries in all. At least 0.limitinteger (int64)requiredSeries per page. At least 0.pageinteger (int64)requiredThe page number, from 0. At least 0.sortBystring or nullThe sort key, echoed.sortDescbooleanrequiredWhether the order is reversed.filterBystring or nullThe filter, echoed.minifiedbooleanrequiredWhether items are minified.includestringrequiredThe include list, echoed.
- 400A query value is out of range. Body: string (
text/plain) - 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 404No such library. Body: string (
text/plain) - 500The library could not be read. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/libraries/<id>/series' \
-H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/libraries/<id>/series' `
-Headers @{ Authorization = 'Bearer <playerToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/player/api/libraries/<id>/series",
headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/libraries/<id>/series", {
headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/player/api/libraries/<id>/series")
.header("Authorization", "Bearer <playerToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: A page of series, each with its items.
{
"results": [
{
"id": "li_8f14e45fceea467f",
"name": "Ann Author",
"nameIgnorePrefix": "Saga, The",
"description": "A short description.",
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"libraryId": "bookclerk-library",
"books": [
{
"id": "li_8f14e45fceea467f",
"ino": "0",
"libraryId": "bookclerk-library",
"folderId": "bookclerk-library",
"path": "/the-first.m4b",
"relPath": "the-first.m4b",
"isFile": true,
"mtimeMs": 1763600000000,
"ctimeMs": 1763600000000,
"birthtimeMs": 1763600000000,
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"isMissing": false,
"isInvalid": false,
"mediaType": "book",
"media": {
"id": "li_8f14e45fceea467f",
"metadata": {
"title": "The First",
"titleIgnorePrefix": "First, The",
"authors": [],
"authorName": "Ann Author",
"authorNameLF": "Author, Ann",
"narrators": [
"Nia Narrator"
],
"narratorName": "Nia Narrator",
"series": [],
"seriesName": "The Saga #1",
"genres": [
"Fantasy"
],
"explicit": false,
"abridged": false
},
"tags": [],
"numTracks": 1,
"numAudioFiles": 1,
"numChapters": 0,
"duration": 36000.0,
"size": 100000
},
"numFiles": 1,
"size": 100000
}
],
"progress": {
"libraryItemIds": [
"li_8f14e45fceea467f"
],
"libraryItemIdsFinished": [],
"isFinished": false
}
}
],
"total": 1,
"limit": 20,
"page": 0,
"sortBy": "media.metadata.title",
"sortDesc": false,
"filterBy": null,
"minified": false,
"include": ""
}
Schema:
{
"type": "object",
"description": "A page of series.",
"required": [
"results",
"total",
"limit",
"page",
"sortDesc",
"minified",
"include"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"description": "A series.",
"required": [
"id",
"name",
"nameIgnorePrefix",
"addedAt",
"updatedAt",
"libraryId"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its name.",
"example": "Ann Author"
},
"nameIgnorePrefix": {
"type": "string",
"description": "The name for sorting.",
"example": "Saga, The"
},
"description": {
"type": [
"string",
"null"
],
"description": "Its description: none.",
"example": "A short description."
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the library first saw it, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When it last changed, in epoch milliseconds.",
"example": 1763630000000
},
"libraryId": {
"type": "string",
"description": "The library it is listed in.",
"example": "bookclerk-library"
},
"books": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "An item: an edition with a stored copy.",
"required": [
"id",
"ino",
"libraryId",
"folderId",
"path",
"relPath",
"isFile",
"mtimeMs",
"ctimeMs",
"birthtimeMs",
"addedAt",
"updatedAt",
"isMissing",
"isInvalid",
"mediaType",
"media",
"numFiles",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The item id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"ino": {
"type": "string",
"description": "The item's inode as apps expect one: the edition id again.",
"example": "0"
},
"oldLibraryItemId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"libraryId": {
"type": "string",
"description": "The library the item is listed in.",
"example": "bookclerk-library"
},
"folderId": {
"type": "string",
"description": "The folder id: the library id.",
"example": "bookclerk-library"
},
"path": {
"type": "string",
"description": "A display path: the title.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the title.",
"example": "the-first.m4b"
},
"isFile": {
"type": "boolean",
"description": "Always false: an item is a folder of tracks.",
"example": true
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy last changed, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the item joined the library, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When its record last changed, in epoch milliseconds.",
"example": 1763630000000
},
"isMissing": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"isInvalid": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"mediaType": {
"type": "string",
"description": "Always [`MEDIA_TYPE_BOOK`].",
"example": "book"
},
"media": {
"type": "object",
"description": "The book.",
"required": [
"id",
"metadata",
"tags",
"numTracks",
"numAudioFiles",
"numChapters",
"duration",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The media id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"libraryItemId": {
"type": [
"string",
"null"
],
"description": "The item id, when fetched expanded.",
"example": "li_8f14e45fceea467f"
},
"metadata": {
"type": "object",
"description": "The book's metadata.",
"required": [
"title",
"titleIgnorePrefix",
"authors",
"authorName",
"authorNameLF",
"narrators",
"narratorName",
"series",
"seriesName",
"genres",
"explicit",
"abridged"
],
"properties": {
"title": {
"type": "string",
"description": "The title.",
"example": "The First"
},
"titleIgnorePrefix": {
"type": "string",
"description": "The title for sorting.",
"example": "First, The"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "The subtitle, if any.",
"example": "A Novel"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"description": "An id and a name.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its display name.",
"example": "Ann Author"
}
}
},
"description": "The authors."
},
"authorName": {
"type": "string",
"description": "The authors' names joined with `, `.",
"example": "Ann Author"
},
"authorNameLF": {
"type": "string",
"description": "The authors' names, family name first, joined with `, `.",
"example": "Author, Ann"
},
"narrators": {
"type": "array",
"items": {
"type": "string"
},
"description": "The narrators' names.",
"example": [
"Nia Narrator"
]
},
"narratorName": {
"type": "string",
"description": "The narrators' names joined with `, `.",
"example": "Nia Narrator"
},
"series": {
"type": "array",
"items": {
"type": "object",
"description": "A series an item belongs to, with the item's place in it.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The series name.",
"example": "Ann Author"
},
"sequence": {
"type": [
"string",
"null"
],
"description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
"example": "1"
}
}
},
"description": "The series the book is in."
},
"seriesName": {
"type": "string",
"description": "The series names with the book's place (`Name #2`), joined.",
"example": "The Saga #1"
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"description": "Genres.",
"example": [
"Fantasy"
]
},
"publishedYear": {
"type": [
"string",
"null"
],
"description": "The year of publication, as a string (`\"2019\"`).",
"example": "2024"
},
"publishedDate": {
"type": [
"string",
"null"
],
"description": "The date of publication, if known.",
"example": "2024-03-01"
},
"publisher": {
"type": [
"string",
"null"
],
"description": "The publisher.",
"example": "Example Press"
},
"description": {
"type": [
"string",
"null"
],
"description": "The description, as the library stores it.",
"example": "A short description."
},
"descriptionPlain": {
"type": [
"string",
"null"
],
"description": "The description with markup removed.",
"example": "A short description."
},
"isbn": {
"type": [
"string",
"null"
],
"description": "The ISBN, if known.",
"example": "9780000000002"
},
"asin": {
"type": [
"string",
"null"
],
"description": "The ASIN, if known.",
"example": "B000000000"
},
"language": {
"type": [
"string",
"null"
],
"description": "The language.",
"example": "en-us"
},
"explicit": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"abridged": {
"type": "boolean",
"description": "Whether the edition is abridged.",
"example": false
}
}
},
"coverPath": {
"type": [
"string",
"null"
],
"description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
"example": "/player/api/items/li_8f14e45fceea467f/cover"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags: none.",
"example": []
},
"numTracks": {
"type": "integer",
"format": "int64",
"description": "Tracks in play order.",
"example": 1,
"minimum": 0
},
"numAudioFiles": {
"type": "integer",
"format": "int64",
"description": "Audio files.",
"example": 1,
"minimum": 0
},
"numChapters": {
"type": "integer",
"format": "int64",
"description": "Chapters.",
"example": 0,
"minimum": 0
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds.",
"example": 36000.0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in its audio files.",
"example": 100000,
"minimum": 0
},
"audioFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "An audio file of a book.",
"required": [
"index",
"ino",
"metadata",
"addedAt",
"updatedAt",
"manuallyVerified",
"exclude",
"duration",
"chapters",
"metaTags",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The file's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"trackNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number the file's tags state: not read.",
"example": 1,
"minimum": 0
},
"discNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number the file's tags state: not read.",
"example": null,
"minimum": 0
},
"trackNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number in the file name: not read.",
"example": null,
"minimum": 0
},
"discNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number in the file name: not read.",
"example": null,
"minimum": 0
},
"manuallyVerified": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"exclude": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"error": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"format": {
"type": [
"string",
"null"
],
"description": "The container format, such as `mp4` or `mp3`.",
"example": "MP4A"
},
"duration": {
"type": "number",
"format": "double",
"description": "The file's length in seconds.",
"example": 36000.0
},
"bitRate": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Bits per second, if known.",
"example": 128000,
"minimum": 0
},
"language": {
"type": [
"string",
"null"
],
"description": "The file's language, if known.",
"example": "en-us"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"timeBase": {
"type": [
"string",
"null"
],
"description": "The time base, if known.",
"example": "1/44100"
},
"channels": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Audio channels, if known.",
"example": 2,
"minimum": 0
},
"channelLayout": {
"type": [
"string",
"null"
],
"description": "The channel layout, if known.",
"example": "stereo"
},
"chapters": {
"type": "array",
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "Chapters embedded in the file: none are read."
},
"embeddedCoverArt": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"metaTags": {
"type": "object",
"description": "Tags read from the file: none until the stored media probe reads\nthem."
},
"mimeType": {
"type": "string",
"description": "The file's media type, such as `audio/mp4`.",
"example": "audio/mp4"
}
}
},
"description": "The audio files, when fetched expanded."
},
"chapters": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "The chapters, when fetched expanded."
},
"tracks": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A track with its place in the book.",
"required": [
"index",
"startOffset",
"duration",
"title",
"contentUrl",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The track's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"startOffset": {
"type": "number",
"format": "double",
"description": "Where the track starts in the book, in seconds.",
"example": 0.0
},
"duration": {
"type": "number",
"format": "double",
"description": "The track's length in seconds.",
"example": 36000.0
},
"title": {
"type": "string",
"description": "The track's title: its file name.",
"example": "The First"
},
"contentUrl": {
"type": "string",
"description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
"example": "/player/api/items/li_8f14e45fceea467f/file/0"
},
"mimeType": {
"type": "string",
"description": "The track's media type.",
"example": "audio/mp4"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"metadata": {
"oneOf": [
{
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "The tracks with their place in the book, when fetched expanded."
}
}
},
"numFiles": {
"type": "integer",
"format": "int64",
"description": "Files in the item.",
"example": 1,
"minimum": 0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in all its files.",
"example": 100000,
"minimum": 0
},
"libraryFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A file of an item, in the expanded item's `libraryFiles`.",
"required": [
"ino",
"metadata",
"addedAt",
"updatedAt",
"fileType"
],
"properties": {
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"fileType": {
"type": "string",
"description": "Always `audio`.",
"example": "audio"
}
}
},
"description": "The item's files, when the item is fetched expanded."
},
"userMediaProgress": {
"oneOf": [
{
"type": "object",
"description": "The patron's progress, when the app asked for it.",
"required": [
"id",
"userId",
"libraryItemId",
"mediaItemId",
"mediaItemType",
"duration",
"progress",
"currentTime",
"isFinished",
"hideFromContinueListening",
"lastUpdate",
"startedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The progress id: the item id (one record per patron and item).",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaItemId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"mediaItemType": {
"type": "string",
"description": "Always `book`.",
"example": "book"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds, as last reported.",
"example": 36000.0
},
"progress": {
"type": "number",
"format": "double",
"description": "The share listened, from 0 to 1.",
"example": 0.05
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished it.",
"example": false
},
"hideFromContinueListening": {
"type": "boolean",
"description": "Whether it is hidden from continue listening.",
"example": false
},
"ebookLocation": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"ebookProgress": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Always null.",
"example": null
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When the progress last changed, in epoch milliseconds.",
"example": 1763630000000
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the patron started, in epoch milliseconds.",
"example": 1763620000000
},
"finishedAt": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron finished, in epoch milliseconds.",
"example": null
}
}
},
{
"type": "null"
}
]
},
"seriesSequence": {
"type": [
"string",
"null"
],
"description": "The item's place in a series, on a series' book list.",
"example": "1"
}
}
},
"description": "Its items in series order, on lists."
},
"progress": {
"oneOf": [
{
"type": "object",
"description": "The patron's progress through it, when asked for.",
"required": [
"libraryItemIds",
"libraryItemIdsFinished",
"isFinished"
],
"properties": {
"libraryItemIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "The series' items, by id.",
"example": [
"li_8f14e45fceea467f"
]
},
"libraryItemIdsFinished": {
"type": "array",
"items": {
"type": "string"
},
"description": "Those the patron finished.",
"example": []
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished every one.",
"example": false
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "The page's series."
},
"total": {
"type": "integer",
"format": "int64",
"description": "Series in all.",
"example": 1,
"minimum": 0
},
"limit": {
"type": "integer",
"format": "int64",
"description": "Series per page.",
"example": 20,
"minimum": 0
},
"page": {
"type": "integer",
"format": "int64",
"description": "The page number, from 0.",
"example": 0,
"minimum": 0
},
"sortBy": {
"type": [
"string",
"null"
],
"description": "The sort key, echoed.",
"example": "media.metadata.title"
},
"sortDesc": {
"type": "boolean",
"description": "Whether the order is reversed.",
"example": false
},
"filterBy": {
"type": [
"string",
"null"
],
"description": "The filter, echoed.",
"example": null
},
"minified": {
"type": "boolean",
"description": "Whether items are minified.",
"example": false
},
"include": {
"type": "string",
"description": "The include list, echoed.",
"example": ""
}
}
}
Status 400: A query value is out of range.
Bad Request
Schema:
A text/plain body: a string.
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 404: No such library.
Not Found
Schema:
A text/plain body: a string.
Status 500: The library could not be read.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Lists the library's authors.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
idpathstringrequiredLibrary id.
- 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 404No such library. Body: string (
text/plain) - 500The library could not be read. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/libraries/<id>/authors' \
-H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/libraries/<id>/authors' `
-Headers @{ Authorization = 'Bearer <playerToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/player/api/libraries/<id>/authors",
headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/libraries/<id>/authors", {
headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/player/api/libraries/<id>/authors")
.header("Authorization", "Bearer <playerToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: Every author, by name (up to 5000).
{
"authors": [
{
"id": "li_8f14e45fceea467f",
"asin": "B000000000",
"name": "Ann Author",
"lastFirst": "Author, Ann",
"description": "A short description.",
"imagePath": null,
"libraryId": "bookclerk-library",
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"numBooks": 1,
"libraryItems": [
{
"id": "li_8f14e45fceea467f",
"ino": "0",
"libraryId": "bookclerk-library",
"folderId": "bookclerk-library",
"path": "/the-first.m4b",
"relPath": "the-first.m4b",
"isFile": true,
"mtimeMs": 1763600000000,
"ctimeMs": 1763600000000,
"birthtimeMs": 1763600000000,
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"isMissing": false,
"isInvalid": false,
"mediaType": "book",
"media": {
"id": "li_8f14e45fceea467f",
"metadata": {
"title": "The First",
"titleIgnorePrefix": "First, The",
"authors": [],
"authorName": "Ann Author",
"authorNameLF": "Author, Ann",
"narrators": [
"Nia Narrator"
],
"narratorName": "Nia Narrator",
"series": [],
"seriesName": "The Saga #1",
"genres": [
"Fantasy"
],
"explicit": false,
"abridged": false
},
"tags": [],
"numTracks": 1,
"numAudioFiles": 1,
"numChapters": 0,
"duration": 36000.0,
"size": 100000
},
"numFiles": 1,
"size": 100000
}
],
"series": [
{
"id": "li_8f14e45fceea467f",
"name": "Ann Author",
"items": []
}
]
}
]
}
Schema:
{
"type": "object",
"description": "`GET /api/libraries/{id}/authors` without paging.",
"required": [
"authors"
],
"properties": {
"authors": {
"type": "array",
"items": {
"type": "object",
"description": "An author.",
"required": [
"id",
"name",
"lastFirst",
"libraryId",
"addedAt",
"updatedAt",
"numBooks"
],
"properties": {
"id": {
"type": "string",
"description": "The contributor id.",
"example": "li_8f14e45fceea467f"
},
"asin": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": "B000000000"
},
"name": {
"type": "string",
"description": "The author's name.",
"example": "Ann Author"
},
"lastFirst": {
"type": "string",
"description": "The name family name first.",
"example": "Author, Ann"
},
"description": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": "A short description."
},
"imagePath": {
"type": [
"string",
"null"
],
"description": "Always null: no author images.",
"example": null
},
"libraryId": {
"type": "string",
"description": "The library it is listed in.",
"example": "bookclerk-library"
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the library first saw the author, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the record last changed, in epoch milliseconds.",
"example": 1763630000000
},
"numBooks": {
"type": "integer",
"format": "int64",
"description": "Items by the author the patron can see.",
"example": 1,
"minimum": 0
},
"libraryItems": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "An item: an edition with a stored copy.",
"required": [
"id",
"ino",
"libraryId",
"folderId",
"path",
"relPath",
"isFile",
"mtimeMs",
"ctimeMs",
"birthtimeMs",
"addedAt",
"updatedAt",
"isMissing",
"isInvalid",
"mediaType",
"media",
"numFiles",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The item id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"ino": {
"type": "string",
"description": "The item's inode as apps expect one: the edition id again.",
"example": "0"
},
"oldLibraryItemId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"libraryId": {
"type": "string",
"description": "The library the item is listed in.",
"example": "bookclerk-library"
},
"folderId": {
"type": "string",
"description": "The folder id: the library id.",
"example": "bookclerk-library"
},
"path": {
"type": "string",
"description": "A display path: the title.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the title.",
"example": "the-first.m4b"
},
"isFile": {
"type": "boolean",
"description": "Always false: an item is a folder of tracks.",
"example": true
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy last changed, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the item joined the library, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When its record last changed, in epoch milliseconds.",
"example": 1763630000000
},
"isMissing": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"isInvalid": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"mediaType": {
"type": "string",
"description": "Always [`MEDIA_TYPE_BOOK`].",
"example": "book"
},
"media": {
"type": "object",
"description": "The book.",
"required": [
"id",
"metadata",
"tags",
"numTracks",
"numAudioFiles",
"numChapters",
"duration",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The media id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"libraryItemId": {
"type": [
"string",
"null"
],
"description": "The item id, when fetched expanded.",
"example": "li_8f14e45fceea467f"
},
"metadata": {
"type": "object",
"description": "The book's metadata.",
"required": [
"title",
"titleIgnorePrefix",
"authors",
"authorName",
"authorNameLF",
"narrators",
"narratorName",
"series",
"seriesName",
"genres",
"explicit",
"abridged"
],
"properties": {
"title": {
"type": "string",
"description": "The title.",
"example": "The First"
},
"titleIgnorePrefix": {
"type": "string",
"description": "The title for sorting.",
"example": "First, The"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "The subtitle, if any.",
"example": "A Novel"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"description": "An id and a name.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its display name.",
"example": "Ann Author"
}
}
},
"description": "The authors."
},
"authorName": {
"type": "string",
"description": "The authors' names joined with `, `.",
"example": "Ann Author"
},
"authorNameLF": {
"type": "string",
"description": "The authors' names, family name first, joined with `, `.",
"example": "Author, Ann"
},
"narrators": {
"type": "array",
"items": {
"type": "string"
},
"description": "The narrators' names.",
"example": [
"Nia Narrator"
]
},
"narratorName": {
"type": "string",
"description": "The narrators' names joined with `, `.",
"example": "Nia Narrator"
},
"series": {
"type": "array",
"items": {
"type": "object",
"description": "A series an item belongs to, with the item's place in it.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The series name.",
"example": "Ann Author"
},
"sequence": {
"type": [
"string",
"null"
],
"description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
"example": "1"
}
}
},
"description": "The series the book is in."
},
"seriesName": {
"type": "string",
"description": "The series names with the book's place (`Name #2`), joined.",
"example": "The Saga #1"
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"description": "Genres.",
"example": [
"Fantasy"
]
},
"publishedYear": {
"type": [
"string",
"null"
],
"description": "The year of publication, as a string (`\"2019\"`).",
"example": "2024"
},
"publishedDate": {
"type": [
"string",
"null"
],
"description": "The date of publication, if known.",
"example": "2024-03-01"
},
"publisher": {
"type": [
"string",
"null"
],
"description": "The publisher.",
"example": "Example Press"
},
"description": {
"type": [
"string",
"null"
],
"description": "The description, as the library stores it.",
"example": "A short description."
},
"descriptionPlain": {
"type": [
"string",
"null"
],
"description": "The description with markup removed.",
"example": "A short description."
},
"isbn": {
"type": [
"string",
"null"
],
"description": "The ISBN, if known.",
"example": "9780000000002"
},
"asin": {
"type": [
"string",
"null"
],
"description": "The ASIN, if known.",
"example": "B000000000"
},
"language": {
"type": [
"string",
"null"
],
"description": "The language.",
"example": "en-us"
},
"explicit": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"abridged": {
"type": "boolean",
"description": "Whether the edition is abridged.",
"example": false
}
}
},
"coverPath": {
"type": [
"string",
"null"
],
"description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
"example": "/player/api/items/li_8f14e45fceea467f/cover"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags: none.",
"example": []
},
"numTracks": {
"type": "integer",
"format": "int64",
"description": "Tracks in play order.",
"example": 1,
"minimum": 0
},
"numAudioFiles": {
"type": "integer",
"format": "int64",
"description": "Audio files.",
"example": 1,
"minimum": 0
},
"numChapters": {
"type": "integer",
"format": "int64",
"description": "Chapters.",
"example": 0,
"minimum": 0
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds.",
"example": 36000.0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in its audio files.",
"example": 100000,
"minimum": 0
},
"audioFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "An audio file of a book.",
"required": [
"index",
"ino",
"metadata",
"addedAt",
"updatedAt",
"manuallyVerified",
"exclude",
"duration",
"chapters",
"metaTags",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The file's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"trackNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number the file's tags state: not read.",
"example": 1,
"minimum": 0
},
"discNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number the file's tags state: not read.",
"example": null,
"minimum": 0
},
"trackNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number in the file name: not read.",
"example": null,
"minimum": 0
},
"discNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number in the file name: not read.",
"example": null,
"minimum": 0
},
"manuallyVerified": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"exclude": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"error": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"format": {
"type": [
"string",
"null"
],
"description": "The container format, such as `mp4` or `mp3`.",
"example": "MP4A"
},
"duration": {
"type": "number",
"format": "double",
"description": "The file's length in seconds.",
"example": 36000.0
},
"bitRate": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Bits per second, if known.",
"example": 128000,
"minimum": 0
},
"language": {
"type": [
"string",
"null"
],
"description": "The file's language, if known.",
"example": "en-us"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"timeBase": {
"type": [
"string",
"null"
],
"description": "The time base, if known.",
"example": "1/44100"
},
"channels": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Audio channels, if known.",
"example": 2,
"minimum": 0
},
"channelLayout": {
"type": [
"string",
"null"
],
"description": "The channel layout, if known.",
"example": "stereo"
},
"chapters": {
"type": "array",
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "Chapters embedded in the file: none are read."
},
"embeddedCoverArt": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"metaTags": {
"type": "object",
"description": "Tags read from the file: none until the stored media probe reads\nthem."
},
"mimeType": {
"type": "string",
"description": "The file's media type, such as `audio/mp4`.",
"example": "audio/mp4"
}
}
},
"description": "The audio files, when fetched expanded."
},
"chapters": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "The chapters, when fetched expanded."
},
"tracks": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A track with its place in the book.",
"required": [
"index",
"startOffset",
"duration",
"title",
"contentUrl",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The track's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"startOffset": {
"type": "number",
"format": "double",
"description": "Where the track starts in the book, in seconds.",
"example": 0.0
},
"duration": {
"type": "number",
"format": "double",
"description": "The track's length in seconds.",
"example": 36000.0
},
"title": {
"type": "string",
"description": "The track's title: its file name.",
"example": "The First"
},
"contentUrl": {
"type": "string",
"description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
"example": "/player/api/items/li_8f14e45fceea467f/file/0"
},
"mimeType": {
"type": "string",
"description": "The track's media type.",
"example": "audio/mp4"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"metadata": {
"oneOf": [
{
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "The tracks with their place in the book, when fetched expanded."
}
}
},
"numFiles": {
"type": "integer",
"format": "int64",
"description": "Files in the item.",
"example": 1,
"minimum": 0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in all its files.",
"example": 100000,
"minimum": 0
},
"libraryFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A file of an item, in the expanded item's `libraryFiles`.",
"required": [
"ino",
"metadata",
"addedAt",
"updatedAt",
"fileType"
],
"properties": {
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"fileType": {
"type": "string",
"description": "Always `audio`.",
"example": "audio"
}
}
},
"description": "The item's files, when the item is fetched expanded."
},
"userMediaProgress": {
"oneOf": [
{
"type": "object",
"description": "The patron's progress, when the app asked for it.",
"required": [
"id",
"userId",
"libraryItemId",
"mediaItemId",
"mediaItemType",
"duration",
"progress",
"currentTime",
"isFinished",
"hideFromContinueListening",
"lastUpdate",
"startedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The progress id: the item id (one record per patron and item).",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaItemId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"mediaItemType": {
"type": "string",
"description": "Always `book`.",
"example": "book"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds, as last reported.",
"example": 36000.0
},
"progress": {
"type": "number",
"format": "double",
"description": "The share listened, from 0 to 1.",
"example": 0.05
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished it.",
"example": false
},
"hideFromContinueListening": {
"type": "boolean",
"description": "Whether it is hidden from continue listening.",
"example": false
},
"ebookLocation": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"ebookProgress": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Always null.",
"example": null
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When the progress last changed, in epoch milliseconds.",
"example": 1763630000000
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the patron started, in epoch milliseconds.",
"example": 1763620000000
},
"finishedAt": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron finished, in epoch milliseconds.",
"example": null
}
}
},
{
"type": "null"
}
]
},
"seriesSequence": {
"type": [
"string",
"null"
],
"description": "The item's place in a series, on a series' book list.",
"example": "1"
}
}
},
"description": "The author's items, when asked for."
},
"series": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A series of an author's, with the author's items in it.",
"required": [
"id",
"name",
"items"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The series name.",
"example": "Ann Author"
},
"items": {
"type": "array",
"items": {
"type": "object",
"description": "An item: an edition with a stored copy.",
"required": [
"id",
"ino",
"libraryId",
"folderId",
"path",
"relPath",
"isFile",
"mtimeMs",
"ctimeMs",
"birthtimeMs",
"addedAt",
"updatedAt",
"isMissing",
"isInvalid",
"mediaType",
"media",
"numFiles",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The item id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"ino": {
"type": "string",
"description": "The item's inode as apps expect one: the edition id again.",
"example": "0"
},
"oldLibraryItemId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"libraryId": {
"type": "string",
"description": "The library the item is listed in.",
"example": "bookclerk-library"
},
"folderId": {
"type": "string",
"description": "The folder id: the library id.",
"example": "bookclerk-library"
},
"path": {
"type": "string",
"description": "A display path: the title.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the title.",
"example": "the-first.m4b"
},
"isFile": {
"type": "boolean",
"description": "Always false: an item is a folder of tracks.",
"example": true
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy last changed, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the item joined the library, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When its record last changed, in epoch milliseconds.",
"example": 1763630000000
},
"isMissing": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"isInvalid": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"mediaType": {
"type": "string",
"description": "Always [`MEDIA_TYPE_BOOK`].",
"example": "book"
},
"media": {
"type": "object",
"description": "The book.",
"required": [
"id",
"metadata",
"tags",
"numTracks",
"numAudioFiles",
"numChapters",
"duration",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The media id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"libraryItemId": {
"type": [
"string",
"null"
],
"description": "The item id, when fetched expanded.",
"example": "li_8f14e45fceea467f"
},
"metadata": {
"type": "object",
"description": "The book's metadata.",
"required": [
"title",
"titleIgnorePrefix",
"authors",
"authorName",
"authorNameLF",
"narrators",
"narratorName",
"series",
"seriesName",
"genres",
"explicit",
"abridged"
],
"properties": {
"title": {
"type": "string",
"description": "The title.",
"example": "The First"
},
"titleIgnorePrefix": {
"type": "string",
"description": "The title for sorting.",
"example": "First, The"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "The subtitle, if any.",
"example": "A Novel"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"description": "An id and a name.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its display name.",
"example": "Ann Author"
}
}
},
"description": "The authors."
},
"authorName": {
"type": "string",
"description": "The authors' names joined with `, `.",
"example": "Ann Author"
},
"authorNameLF": {
"type": "string",
"description": "The authors' names, family name first, joined with `, `.",
"example": "Author, Ann"
},
"narrators": {
"type": "array",
"items": {
"type": "string"
},
"description": "The narrators' names.",
"example": [
"Nia Narrator"
]
},
"narratorName": {
"type": "string",
"description": "The narrators' names joined with `, `.",
"example": "Nia Narrator"
},
"series": {
"type": "array",
"items": {
"type": "object",
"description": "A series an item belongs to, with the item's place in it.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The series name.",
"example": "Ann Author"
},
"sequence": {
"type": [
"string",
"null"
],
"description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
"example": "1"
}
}
},
"description": "The series the book is in."
},
"seriesName": {
"type": "string",
"description": "The series names with the book's place (`Name #2`), joined.",
"example": "The Saga #1"
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"description": "Genres.",
"example": [
"Fantasy"
]
},
"publishedYear": {
"type": [
"string",
"null"
],
"description": "The year of publication, as a string (`\"2019\"`).",
"example": "2024"
},
"publishedDate": {
"type": [
"string",
"null"
],
"description": "The date of publication, if known.",
"example": "2024-03-01"
},
"publisher": {
"type": [
"string",
"null"
],
"description": "The publisher.",
"example": "Example Press"
},
"description": {
"type": [
"string",
"null"
],
"description": "The description, as the library stores it.",
"example": "A short description."
},
"descriptionPlain": {
"type": [
"string",
"null"
],
"description": "The description with markup removed.",
"example": "A short description."
},
"isbn": {
"type": [
"string",
"null"
],
"description": "The ISBN, if known.",
"example": "9780000000002"
},
"asin": {
"type": [
"string",
"null"
],
"description": "The ASIN, if known.",
"example": "B000000000"
},
"language": {
"type": [
"string",
"null"
],
"description": "The language.",
"example": "en-us"
},
"explicit": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"abridged": {
"type": "boolean",
"description": "Whether the edition is abridged.",
"example": false
}
}
},
"coverPath": {
"type": [
"string",
"null"
],
"description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
"example": "/player/api/items/li_8f14e45fceea467f/cover"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags: none.",
"example": []
},
"numTracks": {
"type": "integer",
"format": "int64",
"description": "Tracks in play order.",
"example": 1,
"minimum": 0
},
"numAudioFiles": {
"type": "integer",
"format": "int64",
"description": "Audio files.",
"example": 1,
"minimum": 0
},
"numChapters": {
"type": "integer",
"format": "int64",
"description": "Chapters.",
"example": 0,
"minimum": 0
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds.",
"example": 36000.0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in its audio files.",
"example": 100000,
"minimum": 0
},
"audioFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "An audio file of a book.",
"required": [
"index",
"ino",
"metadata",
"addedAt",
"updatedAt",
"manuallyVerified",
"exclude",
"duration",
"chapters",
"metaTags",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The file's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"trackNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number the file's tags state: not read.",
"example": 1,
"minimum": 0
},
"discNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number the file's tags state: not read.",
"example": null,
"minimum": 0
},
"trackNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number in the file name: not read.",
"example": null,
"minimum": 0
},
"discNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number in the file name: not read.",
"example": null,
"minimum": 0
},
"manuallyVerified": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"exclude": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"error": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"format": {
"type": [
"string",
"null"
],
"description": "The container format, such as `mp4` or `mp3`.",
"example": "MP4A"
},
"duration": {
"type": "number",
"format": "double",
"description": "The file's length in seconds.",
"example": 36000.0
},
"bitRate": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Bits per second, if known.",
"example": 128000,
"minimum": 0
},
"language": {
"type": [
"string",
"null"
],
"description": "The file's language, if known.",
"example": "en-us"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"timeBase": {
"type": [
"string",
"null"
],
"description": "The time base, if known.",
"example": "1/44100"
},
"channels": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Audio channels, if known.",
"example": 2,
"minimum": 0
},
"channelLayout": {
"type": [
"string",
"null"
],
"description": "The channel layout, if known.",
"example": "stereo"
},
"chapters": {
"type": "array",
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "Chapters embedded in the file: none are read."
},
"embeddedCoverArt": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"metaTags": {
"type": "object",
"description": "Tags read from the file: none until the stored media probe reads\nthem."
},
"mimeType": {
"type": "string",
"description": "The file's media type, such as `audio/mp4`.",
"example": "audio/mp4"
}
}
},
"description": "The audio files, when fetched expanded."
},
"chapters": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "The chapters, when fetched expanded."
},
"tracks": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A track with its place in the book.",
"required": [
"index",
"startOffset",
"duration",
"title",
"contentUrl",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The track's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"startOffset": {
"type": "number",
"format": "double",
"description": "Where the track starts in the book, in seconds.",
"example": 0.0
},
"duration": {
"type": "number",
"format": "double",
"description": "The track's length in seconds.",
"example": 36000.0
},
"title": {
"type": "string",
"description": "The track's title: its file name.",
"example": "The First"
},
"contentUrl": {
"type": "string",
"description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
"example": "/player/api/items/li_8f14e45fceea467f/file/0"
},
"mimeType": {
"type": "string",
"description": "The track's media type.",
"example": "audio/mp4"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"metadata": {
"oneOf": [
{
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "The tracks with their place in the book, when fetched expanded."
}
}
},
"numFiles": {
"type": "integer",
"format": "int64",
"description": "Files in the item.",
"example": 1,
"minimum": 0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in all its files.",
"example": 100000,
"minimum": 0
},
"libraryFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A file of an item, in the expanded item's `libraryFiles`.",
"required": [
"ino",
"metadata",
"addedAt",
"updatedAt",
"fileType"
],
"properties": {
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"fileType": {
"type": "string",
"description": "Always `audio`.",
"example": "audio"
}
}
},
"description": "The item's files, when the item is fetched expanded."
},
"userMediaProgress": {
"oneOf": [
{
"type": "object",
"description": "The patron's progress, when the app asked for it.",
"required": [
"id",
"userId",
"libraryItemId",
"mediaItemId",
"mediaItemType",
"duration",
"progress",
"currentTime",
"isFinished",
"hideFromContinueListening",
"lastUpdate",
"startedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The progress id: the item id (one record per patron and item).",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaItemId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"mediaItemType": {
"type": "string",
"description": "Always `book`.",
"example": "book"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds, as last reported.",
"example": 36000.0
},
"progress": {
"type": "number",
"format": "double",
"description": "The share listened, from 0 to 1.",
"example": 0.05
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished it.",
"example": false
},
"hideFromContinueListening": {
"type": "boolean",
"description": "Whether it is hidden from continue listening.",
"example": false
},
"ebookLocation": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"ebookProgress": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Always null.",
"example": null
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When the progress last changed, in epoch milliseconds.",
"example": 1763630000000
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the patron started, in epoch milliseconds.",
"example": 1763620000000
},
"finishedAt": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron finished, in epoch milliseconds.",
"example": null
}
}
},
{
"type": "null"
}
]
},
"seriesSequence": {
"type": [
"string",
"null"
],
"description": "The item's place in a series, on a series' book list.",
"example": "1"
}
}
},
"description": "The items, in series order."
}
}
},
"description": "The author's series with their items, when asked for."
}
}
},
"description": "The authors."
}
}
}
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 404: No such library.
Not Found
Schema:
A text/plain body: a string.
Status 500: The library could not be read.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Lists the library's narrators.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
idpathstringrequiredLibrary id.
- 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 404No such library. Body: string (
text/plain) - 500The library could not be read. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/libraries/<id>/narrators' \
-H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/libraries/<id>/narrators' `
-Headers @{ Authorization = 'Bearer <playerToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/player/api/libraries/<id>/narrators",
headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/libraries/<id>/narrators", {
headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/player/api/libraries/<id>/narrators")
.header("Authorization", "Bearer <playerToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: Every narrator, by name (up to 5000).
{
"narrators": [
{
"id": "li_8f14e45fceea467f",
"name": "Ann Author",
"numBooks": 1
}
]
}
Schema:
{
"type": "object",
"description": "`GET /api/libraries/{id}/narrators`.",
"required": [
"narrators"
],
"properties": {
"narrators": {
"type": "array",
"items": {
"type": "object",
"description": "A narrator with how many items they read.",
"required": [
"id",
"name",
"numBooks"
],
"properties": {
"id": {
"type": "string",
"description": "The name in URL-safe base64, as apps filter by it.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The narrator's name.",
"example": "Ann Author"
},
"numBooks": {
"type": "integer",
"format": "int64",
"description": "Items they read that the patron can see.",
"example": 1,
"minimum": 0
}
}
},
"description": "The narrators."
}
}
}
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 404: No such library.
Not Found
Schema:
A text/plain body: a string.
Status 500: The library could not be read.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Lists the library's collections: none yet.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
idpathstringrequiredLibrary id.
-
200An empty page. Body:
EmptyPage(application/json)4 fieldsresultsarray of objectrequiredAlways empty.totalinteger (int64)requiredAlways 0. At least 0.limitinteger (int64)requiredItems per page, echoed. At least 0.pageinteger (int64)requiredThe page number, echoed. At least 0.
- 400A query value is out of range. Body: string (
text/plain) - 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 404No such library. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/libraries/<id>/collections' \
-H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/libraries/<id>/collections' `
-Headers @{ Authorization = 'Bearer <playerToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/player/api/libraries/<id>/collections",
headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/libraries/<id>/collections", {
headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/player/api/libraries/<id>/collections")
.header("Authorization", "Bearer <playerToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: An empty page.
{
"results": [],
"total": 1,
"limit": 20,
"page": 0
}
Schema:
{
"type": "object",
"description": "An empty page, for collections and playlists the library does not\nhave yet.",
"required": [
"results",
"total",
"limit",
"page"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object"
},
"description": "Always empty.",
"example": []
},
"total": {
"type": "integer",
"format": "int64",
"description": "Always 0.",
"example": 1,
"minimum": 0
},
"limit": {
"type": "integer",
"format": "int64",
"description": "Items per page, echoed.",
"example": 20,
"minimum": 0
},
"page": {
"type": "integer",
"format": "int64",
"description": "The page number, echoed.",
"example": 0,
"minimum": 0
}
}
}
Status 400: A query value is out of range.
Bad Request
Schema:
A text/plain body: a string.
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 404: No such library.
Not Found
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Lists the patron's playlists in the library: none yet.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
idpathstringrequiredLibrary id.
-
200An empty page. Body:
EmptyPage(application/json)4 fieldsresultsarray of objectrequiredAlways empty.totalinteger (int64)requiredAlways 0. At least 0.limitinteger (int64)requiredItems per page, echoed. At least 0.pageinteger (int64)requiredThe page number, echoed. At least 0.
- 400A query value is out of range. Body: string (
text/plain) - 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 404No such library. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/libraries/<id>/playlists' \
-H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/libraries/<id>/playlists' `
-Headers @{ Authorization = 'Bearer <playerToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/player/api/libraries/<id>/playlists",
headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/libraries/<id>/playlists", {
headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/player/api/libraries/<id>/playlists")
.header("Authorization", "Bearer <playerToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: An empty page.
{
"results": [],
"total": 1,
"limit": 20,
"page": 0
}
Schema:
{
"type": "object",
"description": "An empty page, for collections and playlists the library does not\nhave yet.",
"required": [
"results",
"total",
"limit",
"page"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object"
},
"description": "Always empty.",
"example": []
},
"total": {
"type": "integer",
"format": "int64",
"description": "Always 0.",
"example": 1,
"minimum": 0
},
"limit": {
"type": "integer",
"format": "int64",
"description": "Items per page, echoed.",
"example": 20,
"minimum": 0
},
"page": {
"type": "integer",
"format": "int64",
"description": "The page number, echoed.",
"example": 0,
"minimum": 0
}
}
}
Status 400: A query value is out of range.
Bad Request
Schema:
A text/plain body: a string.
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 404: No such library.
Not Found
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Reads the patron's home shelves: continue listening, recently added and listen again.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
idpathstringrequiredLibrary id.
-
200The shelves that have items. Body: array of
Shelf(application/json)6 fieldsidstringrequiredThe shelf id, such ascontinue-listening.labelstringrequiredThe shelf's English label.labelStringKeystringrequiredThe key apps translate the label by.typestringrequiredWhat the shelf holds:book,seriesorauthors.entitiesShelfEntitiesrequiredThe shelf's entries.totalinteger (int64)requiredEntries in all. At least 0.
- 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 404No such library. Body: string (
text/plain) - 500The library could not be read. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/libraries/<id>/personalized' \
-H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/libraries/<id>/personalized' `
-Headers @{ Authorization = 'Bearer <playerToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/player/api/libraries/<id>/personalized",
headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/libraries/<id>/personalized", {
headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/player/api/libraries/<id>/personalized")
.header("Authorization", "Bearer <playerToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The shelves that have items.
[
{
"id": "li_8f14e45fceea467f",
"label": "Continue Listening",
"labelStringKey": "LabelContinueListening",
"type": "user",
"entities": [
{
"id": "li_8f14e45fceea467f",
"ino": "0",
"oldLibraryItemId": null,
"libraryId": "bookclerk-library",
"folderId": "bookclerk-library",
"path": "/the-first.m4b",
"relPath": "the-first.m4b",
"isFile": true,
"mtimeMs": 1763600000000,
"ctimeMs": 1763600000000,
"birthtimeMs": 1763600000000,
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"isMissing": false,
"isInvalid": false,
"mediaType": "book",
"media": {
"id": "li_8f14e45fceea467f",
"metadata": {
"title": "The First",
"titleIgnorePrefix": "First, The",
"authors": [],
"authorName": "Ann Author",
"authorNameLF": "Author, Ann",
"narrators": [
"Nia Narrator"
],
"narratorName": "Nia Narrator",
"series": [],
"seriesName": "The Saga #1",
"genres": [
"Fantasy"
],
"explicit": false,
"abridged": false
},
"tags": [],
"numTracks": 1,
"numAudioFiles": 1,
"numChapters": 0,
"duration": 36000.0,
"size": 100000
},
"numFiles": 1,
"size": 100000,
"libraryFiles": [],
"userMediaProgress": {
"id": "li_8f14e45fceea467f",
"userId": "42",
"libraryItemId": "li_8f14e45fceea467f",
"mediaItemId": "li_8f14e45fceea467f",
"mediaItemType": "book",
"duration": 36000.0,
"progress": 0.05,
"currentTime": 1830.5,
"isFinished": false,
"hideFromContinueListening": false,
"lastUpdate": 1763630000000,
"startedAt": 1763620000000
},
"seriesSequence": "1"
}
],
"total": 1
}
]
Schema:
{
"type": "array",
"items": {
"type": "object",
"description": "A personalized shelf on the home screen.",
"required": [
"id",
"label",
"labelStringKey",
"type",
"entities",
"total"
],
"properties": {
"id": {
"type": "string",
"description": "The shelf id, such as `continue-listening`.",
"example": "li_8f14e45fceea467f"
},
"label": {
"type": "string",
"description": "The shelf's English label.",
"example": "Continue Listening"
},
"labelStringKey": {
"type": "string",
"description": "The key apps translate the label by.",
"example": "LabelContinueListening"
},
"type": {
"type": "string",
"description": "What the shelf holds: `book`, `series` or `authors`.",
"example": "user"
},
"entities": {
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"description": "An item: an edition with a stored copy.",
"required": [
"id",
"ino",
"libraryId",
"folderId",
"path",
"relPath",
"isFile",
"mtimeMs",
"ctimeMs",
"birthtimeMs",
"addedAt",
"updatedAt",
"isMissing",
"isInvalid",
"mediaType",
"media",
"numFiles",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The item id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"ino": {
"type": "string",
"description": "The item's inode as apps expect one: the edition id again.",
"example": "0"
},
"oldLibraryItemId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"libraryId": {
"type": "string",
"description": "The library the item is listed in.",
"example": "bookclerk-library"
},
"folderId": {
"type": "string",
"description": "The folder id: the library id.",
"example": "bookclerk-library"
},
"path": {
"type": "string",
"description": "A display path: the title.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the title.",
"example": "the-first.m4b"
},
"isFile": {
"type": "boolean",
"description": "Always false: an item is a folder of tracks.",
"example": true
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy last changed, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the item joined the library, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When its record last changed, in epoch milliseconds.",
"example": 1763630000000
},
"isMissing": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"isInvalid": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"mediaType": {
"type": "string",
"description": "Always [`MEDIA_TYPE_BOOK`].",
"example": "book"
},
"media": {
"type": "object",
"description": "The book.",
"required": [
"id",
"metadata",
"tags",
"numTracks",
"numAudioFiles",
"numChapters",
"duration",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The media id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"libraryItemId": {
"type": [
"string",
"null"
],
"description": "The item id, when fetched expanded.",
"example": "li_8f14e45fceea467f"
},
"metadata": {
"type": "object",
"description": "The book's metadata.",
"required": [
"title",
"titleIgnorePrefix",
"authors",
"authorName",
"authorNameLF",
"narrators",
"narratorName",
"series",
"seriesName",
"genres",
"explicit",
"abridged"
],
"properties": {
"title": {
"type": "string",
"description": "The title.",
"example": "The First"
},
"titleIgnorePrefix": {
"type": "string",
"description": "The title for sorting.",
"example": "First, The"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "The subtitle, if any.",
"example": "A Novel"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"description": "An id and a name.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its display name.",
"example": "Ann Author"
}
}
},
"description": "The authors."
},
"authorName": {
"type": "string",
"description": "The authors' names joined with `, `.",
"example": "Ann Author"
},
"authorNameLF": {
"type": "string",
"description": "The authors' names, family name first, joined with `, `.",
"example": "Author, Ann"
},
"narrators": {
"type": "array",
"items": {
"type": "string"
},
"description": "The narrators' names.",
"example": [
"Nia Narrator"
]
},
"narratorName": {
"type": "string",
"description": "The narrators' names joined with `, `.",
"example": "Nia Narrator"
},
"series": {
"type": "array",
"items": {
"type": "object",
"description": "A series an item belongs to, with the item's place in it.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The series name.",
"example": "Ann Author"
},
"sequence": {
"type": [
"string",
"null"
],
"description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
"example": "1"
}
}
},
"description": "The series the book is in."
},
"seriesName": {
"type": "string",
"description": "The series names with the book's place (`Name #2`), joined.",
"example": "The Saga #1"
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"description": "Genres.",
"example": [
"Fantasy"
]
},
"publishedYear": {
"type": [
"string",
"null"
],
"description": "The year of publication, as a string (`\"2019\"`).",
"example": "2024"
},
"publishedDate": {
"type": [
"string",
"null"
],
"description": "The date of publication, if known.",
"example": "2024-03-01"
},
"publisher": {
"type": [
"string",
"null"
],
"description": "The publisher.",
"example": "Example Press"
},
"description": {
"type": [
"string",
"null"
],
"description": "The description, as the library stores it.",
"example": "A short description."
},
"descriptionPlain": {
"type": [
"string",
"null"
],
"description": "The description with markup removed.",
"example": "A short description."
},
"isbn": {
"type": [
"string",
"null"
],
"description": "The ISBN, if known.",
"example": "9780000000002"
},
"asin": {
"type": [
"string",
"null"
],
"description": "The ASIN, if known.",
"example": "B000000000"
},
"language": {
"type": [
"string",
"null"
],
"description": "The language.",
"example": "en-us"
},
"explicit": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"abridged": {
"type": "boolean",
"description": "Whether the edition is abridged.",
"example": false
}
}
},
"coverPath": {
"type": [
"string",
"null"
],
"description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
"example": "/player/api/items/li_8f14e45fceea467f/cover"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags: none.",
"example": []
},
"numTracks": {
"type": "integer",
"format": "int64",
"description": "Tracks in play order.",
"example": 1,
"minimum": 0
},
"numAudioFiles": {
"type": "integer",
"format": "int64",
"description": "Audio files.",
"example": 1,
"minimum": 0
},
"numChapters": {
"type": "integer",
"format": "int64",
"description": "Chapters.",
"example": 0,
"minimum": 0
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds.",
"example": 36000.0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in its audio files.",
"example": 100000,
"minimum": 0
},
"audioFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "An audio file of a book.",
"required": [
"index",
"ino",
"metadata",
"addedAt",
"updatedAt",
"manuallyVerified",
"exclude",
"duration",
"chapters",
"metaTags",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The file's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"trackNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number the file's tags state: not read.",
"example": 1,
"minimum": 0
},
"discNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number the file's tags state: not read.",
"example": null,
"minimum": 0
},
"trackNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number in the file name: not read.",
"example": null,
"minimum": 0
},
"discNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number in the file name: not read.",
"example": null,
"minimum": 0
},
"manuallyVerified": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"exclude": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"error": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"format": {
"type": [
"string",
"null"
],
"description": "The container format, such as `mp4` or `mp3`.",
"example": "MP4A"
},
"duration": {
"type": "number",
"format": "double",
"description": "The file's length in seconds.",
"example": 36000.0
},
"bitRate": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Bits per second, if known.",
"example": 128000,
"minimum": 0
},
"language": {
"type": [
"string",
"null"
],
"description": "The file's language, if known.",
"example": "en-us"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"timeBase": {
"type": [
"string",
"null"
],
"description": "The time base, if known.",
"example": "1/44100"
},
"channels": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Audio channels, if known.",
"example": 2,
"minimum": 0
},
"channelLayout": {
"type": [
"string",
"null"
],
"description": "The channel layout, if known.",
"example": "stereo"
},
"chapters": {
"type": "array",
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "Chapters embedded in the file: none are read."
},
"embeddedCoverArt": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"metaTags": {
"type": "object",
"description": "Tags read from the file: none until the stored media probe reads\nthem."
},
"mimeType": {
"type": "string",
"description": "The file's media type, such as `audio/mp4`.",
"example": "audio/mp4"
}
}
},
"description": "The audio files, when fetched expanded."
},
"chapters": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "The chapters, when fetched expanded."
},
"tracks": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A track with its place in the book.",
"required": [
"index",
"startOffset",
"duration",
"title",
"contentUrl",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The track's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"startOffset": {
"type": "number",
"format": "double",
"description": "Where the track starts in the book, in seconds.",
"example": 0.0
},
"duration": {
"type": "number",
"format": "double",
"description": "The track's length in seconds.",
"example": 36000.0
},
"title": {
"type": "string",
"description": "The track's title: its file name.",
"example": "The First"
},
"contentUrl": {
"type": "string",
"description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
"example": "/player/api/items/li_8f14e45fceea467f/file/0"
},
"mimeType": {
"type": "string",
"description": "The track's media type.",
"example": "audio/mp4"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"metadata": {
"oneOf": [
{
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "The tracks with their place in the book, when fetched expanded."
}
}
},
"numFiles": {
"type": "integer",
"format": "int64",
"description": "Files in the item.",
"example": 1,
"minimum": 0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in all its files.",
"example": 100000,
"minimum": 0
},
"libraryFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A file of an item, in the expanded item's `libraryFiles`.",
"required": [
"ino",
"metadata",
"addedAt",
"updatedAt",
"fileType"
],
"properties": {
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"fileType": {
"type": "string",
"description": "Always `audio`.",
"example": "audio"
}
}
},
"description": "The item's files, when the item is fetched expanded."
},
"userMediaProgress": {
"oneOf": [
{
"type": "object",
"description": "The patron's progress, when the app asked for it.",
"required": [
"id",
"userId",
"libraryItemId",
"mediaItemId",
"mediaItemType",
"duration",
"progress",
"currentTime",
"isFinished",
"hideFromContinueListening",
"lastUpdate",
"startedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The progress id: the item id (one record per patron and item).",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaItemId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"mediaItemType": {
"type": "string",
"description": "Always `book`.",
"example": "book"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds, as last reported.",
"example": 36000.0
},
"progress": {
"type": "number",
"format": "double",
"description": "The share listened, from 0 to 1.",
"example": 0.05
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished it.",
"example": false
},
"hideFromContinueListening": {
"type": "boolean",
"description": "Whether it is hidden from continue listening.",
"example": false
},
"ebookLocation": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"ebookProgress": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Always null.",
"example": null
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When the progress last changed, in epoch milliseconds.",
"example": 1763630000000
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the patron started, in epoch milliseconds.",
"example": 1763620000000
},
"finishedAt": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron finished, in epoch milliseconds.",
"example": null
}
}
},
{
"type": "null"
}
]
},
"seriesSequence": {
"type": [
"string",
"null"
],
"description": "The item's place in a series, on a series' book list.",
"example": "1"
}
}
},
"description": "Items."
},
{
"type": "array",
"items": {
"type": "object",
"description": "A series.",
"required": [
"id",
"name",
"nameIgnorePrefix",
"addedAt",
"updatedAt",
"libraryId"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its name.",
"example": "Ann Author"
},
"nameIgnorePrefix": {
"type": "string",
"description": "The name for sorting.",
"example": "Saga, The"
},
"description": {
"type": [
"string",
"null"
],
"description": "Its description: none.",
"example": "A short description."
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the library first saw it, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When it last changed, in epoch milliseconds.",
"example": 1763630000000
},
"libraryId": {
"type": "string",
"description": "The library it is listed in.",
"example": "bookclerk-library"
},
"books": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "An item: an edition with a stored copy.",
"required": [
"id",
"ino",
"libraryId",
"folderId",
"path",
"relPath",
"isFile",
"mtimeMs",
"ctimeMs",
"birthtimeMs",
"addedAt",
"updatedAt",
"isMissing",
"isInvalid",
"mediaType",
"media",
"numFiles",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The item id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"ino": {
"type": "string",
"description": "The item's inode as apps expect one: the edition id again.",
"example": "0"
},
"oldLibraryItemId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"libraryId": {
"type": "string",
"description": "The library the item is listed in.",
"example": "bookclerk-library"
},
"folderId": {
"type": "string",
"description": "The folder id: the library id.",
"example": "bookclerk-library"
},
"path": {
"type": "string",
"description": "A display path: the title.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the title.",
"example": "the-first.m4b"
},
"isFile": {
"type": "boolean",
"description": "Always false: an item is a folder of tracks.",
"example": true
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy last changed, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the item joined the library, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When its record last changed, in epoch milliseconds.",
"example": 1763630000000
},
"isMissing": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"isInvalid": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"mediaType": {
"type": "string",
"description": "Always [`MEDIA_TYPE_BOOK`].",
"example": "book"
},
"media": {
"type": "object",
"description": "The book.",
"required": [
"id",
"metadata",
"tags",
"numTracks",
"numAudioFiles",
"numChapters",
"duration",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The media id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"libraryItemId": {
"type": [
"string",
"null"
],
"description": "The item id, when fetched expanded.",
"example": "li_8f14e45fceea467f"
},
"metadata": {
"type": "object",
"description": "The book's metadata.",
"required": [
"title",
"titleIgnorePrefix",
"authors",
"authorName",
"authorNameLF",
"narrators",
"narratorName",
"series",
"seriesName",
"genres",
"explicit",
"abridged"
],
"properties": {
"title": {
"type": "string",
"description": "The title.",
"example": "The First"
},
"titleIgnorePrefix": {
"type": "string",
"description": "The title for sorting.",
"example": "First, The"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "The subtitle, if any.",
"example": "A Novel"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"description": "An id and a name.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its display name.",
"example": "Ann Author"
}
}
},
"description": "The authors."
},
"authorName": {
"type": "string",
"description": "The authors' names joined with `, `.",
"example": "Ann Author"
},
"authorNameLF": {
"type": "string",
"description": "The authors' names, family name first, joined with `, `.",
"example": "Author, Ann"
},
"narrators": {
"type": "array",
"items": {
"type": "string"
},
"description": "The narrators' names.",
"example": [
"Nia Narrator"
]
},
"narratorName": {
"type": "string",
"description": "The narrators' names joined with `, `.",
"example": "Nia Narrator"
},
"series": {
"type": "array",
"items": {
"type": "object",
"description": "A series an item belongs to, with the item's place in it.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The series name.",
"example": "Ann Author"
},
"sequence": {
"type": [
"string",
"null"
],
"description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
"example": "1"
}
}
},
"description": "The series the book is in."
},
"seriesName": {
"type": "string",
"description": "The series names with the book's place (`Name #2`), joined.",
"example": "The Saga #1"
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"description": "Genres.",
"example": [
"Fantasy"
]
},
"publishedYear": {
"type": [
"string",
"null"
],
"description": "The year of publication, as a string (`\"2019\"`).",
"example": "2024"
},
"publishedDate": {
"type": [
"string",
"null"
],
"description": "The date of publication, if known.",
"example": "2024-03-01"
},
"publisher": {
"type": [
"string",
"null"
],
"description": "The publisher.",
"example": "Example Press"
},
"description": {
"type": [
"string",
"null"
],
"description": "The description, as the library stores it.",
"example": "A short description."
},
"descriptionPlain": {
"type": [
"string",
"null"
],
"description": "The description with markup removed.",
"example": "A short description."
},
"isbn": {
"type": [
"string",
"null"
],
"description": "The ISBN, if known.",
"example": "9780000000002"
},
"asin": {
"type": [
"string",
"null"
],
"description": "The ASIN, if known.",
"example": "B000000000"
},
"language": {
"type": [
"string",
"null"
],
"description": "The language.",
"example": "en-us"
},
"explicit": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"abridged": {
"type": "boolean",
"description": "Whether the edition is abridged.",
"example": false
}
}
},
"coverPath": {
"type": [
"string",
"null"
],
"description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
"example": "/player/api/items/li_8f14e45fceea467f/cover"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags: none.",
"example": []
},
"numTracks": {
"type": "integer",
"format": "int64",
"description": "Tracks in play order.",
"example": 1,
"minimum": 0
},
"numAudioFiles": {
"type": "integer",
"format": "int64",
"description": "Audio files.",
"example": 1,
"minimum": 0
},
"numChapters": {
"type": "integer",
"format": "int64",
"description": "Chapters.",
"example": 0,
"minimum": 0
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds.",
"example": 36000.0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in its audio files.",
"example": 100000,
"minimum": 0
},
"audioFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "An audio file of a book.",
"required": [
"index",
"ino",
"metadata",
"addedAt",
"updatedAt",
"manuallyVerified",
"exclude",
"duration",
"chapters",
"metaTags",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The file's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"trackNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number the file's tags state: not read.",
"example": 1,
"minimum": 0
},
"discNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number the file's tags state: not read.",
"example": null,
"minimum": 0
},
"trackNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number in the file name: not read.",
"example": null,
"minimum": 0
},
"discNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number in the file name: not read.",
"example": null,
"minimum": 0
},
"manuallyVerified": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"exclude": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"error": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"format": {
"type": [
"string",
"null"
],
"description": "The container format, such as `mp4` or `mp3`.",
"example": "MP4A"
},
"duration": {
"type": "number",
"format": "double",
"description": "The file's length in seconds.",
"example": 36000.0
},
"bitRate": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Bits per second, if known.",
"example": 128000,
"minimum": 0
},
"language": {
"type": [
"string",
"null"
],
"description": "The file's language, if known.",
"example": "en-us"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"timeBase": {
"type": [
"string",
"null"
],
"description": "The time base, if known.",
"example": "1/44100"
},
"channels": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Audio channels, if known.",
"example": 2,
"minimum": 0
},
"channelLayout": {
"type": [
"string",
"null"
],
"description": "The channel layout, if known.",
"example": "stereo"
},
"chapters": {
"type": "array",
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "Chapters embedded in the file: none are read."
},
"embeddedCoverArt": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"metaTags": {
"type": "object",
"description": "Tags read from the file: none until the stored media probe reads\nthem."
},
"mimeType": {
"type": "string",
"description": "The file's media type, such as `audio/mp4`.",
"example": "audio/mp4"
}
}
},
"description": "The audio files, when fetched expanded."
},
"chapters": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "The chapters, when fetched expanded."
},
"tracks": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A track with its place in the book.",
"required": [
"index",
"startOffset",
"duration",
"title",
"contentUrl",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The track's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"startOffset": {
"type": "number",
"format": "double",
"description": "Where the track starts in the book, in seconds.",
"example": 0.0
},
"duration": {
"type": "number",
"format": "double",
"description": "The track's length in seconds.",
"example": 36000.0
},
"title": {
"type": "string",
"description": "The track's title: its file name.",
"example": "The First"
},
"contentUrl": {
"type": "string",
"description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
"example": "/player/api/items/li_8f14e45fceea467f/file/0"
},
"mimeType": {
"type": "string",
"description": "The track's media type.",
"example": "audio/mp4"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"metadata": {
"oneOf": [
{
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "The tracks with their place in the book, when fetched expanded."
}
}
},
"numFiles": {
"type": "integer",
"format": "int64",
"description": "Files in the item.",
"example": 1,
"minimum": 0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in all its files.",
"example": 100000,
"minimum": 0
},
"libraryFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A file of an item, in the expanded item's `libraryFiles`.",
"required": [
"ino",
"metadata",
"addedAt",
"updatedAt",
"fileType"
],
"properties": {
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"fileType": {
"type": "string",
"description": "Always `audio`.",
"example": "audio"
}
}
},
"description": "The item's files, when the item is fetched expanded."
},
"userMediaProgress": {
"oneOf": [
{
"type": "object",
"description": "The patron's progress, when the app asked for it.",
"required": [
"id",
"userId",
"libraryItemId",
"mediaItemId",
"mediaItemType",
"duration",
"progress",
"currentTime",
"isFinished",
"hideFromContinueListening",
"lastUpdate",
"startedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The progress id: the item id (one record per patron and item).",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaItemId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"mediaItemType": {
"type": "string",
"description": "Always `book`.",
"example": "book"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds, as last reported.",
"example": 36000.0
},
"progress": {
"type": "number",
"format": "double",
"description": "The share listened, from 0 to 1.",
"example": 0.05
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished it.",
"example": false
},
"hideFromContinueListening": {
"type": "boolean",
"description": "Whether it is hidden from continue listening.",
"example": false
},
"ebookLocation": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"ebookProgress": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Always null.",
"example": null
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When the progress last changed, in epoch milliseconds.",
"example": 1763630000000
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the patron started, in epoch milliseconds.",
"example": 1763620000000
},
"finishedAt": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron finished, in epoch milliseconds.",
"example": null
}
}
},
{
"type": "null"
}
]
},
"seriesSequence": {
"type": [
"string",
"null"
],
"description": "The item's place in a series, on a series' book list.",
"example": "1"
}
}
},
"description": "Its items in series order, on lists."
},
"progress": {
"oneOf": [
{
"type": "object",
"description": "The patron's progress through it, when asked for.",
"required": [
"libraryItemIds",
"libraryItemIdsFinished",
"isFinished"
],
"properties": {
"libraryItemIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "The series' items, by id.",
"example": [
"li_8f14e45fceea467f"
]
},
"libraryItemIdsFinished": {
"type": "array",
"items": {
"type": "string"
},
"description": "Those the patron finished.",
"example": []
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished every one.",
"example": false
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "Series."
},
{
"type": "array",
"items": {
"type": "object",
"description": "An author.",
"required": [
"id",
"name",
"lastFirst",
"libraryId",
"addedAt",
"updatedAt",
"numBooks"
],
"properties": {
"id": {
"type": "string",
"description": "The contributor id.",
"example": "li_8f14e45fceea467f"
},
"asin": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": "B000000000"
},
"name": {
"type": "string",
"description": "The author's name.",
"example": "Ann Author"
},
"lastFirst": {
"type": "string",
"description": "The name family name first.",
"example": "Author, Ann"
},
"description": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": "A short description."
},
"imagePath": {
"type": [
"string",
"null"
],
"description": "Always null: no author images.",
"example": null
},
"libraryId": {
"type": "string",
"description": "The library it is listed in.",
"example": "bookclerk-library"
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the library first saw the author, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the record last changed, in epoch milliseconds.",
"example": 1763630000000
},
"numBooks": {
"type": "integer",
"format": "int64",
"description": "Items by the author the patron can see.",
"example": 1,
"minimum": 0
},
"libraryItems": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "An item: an edition with a stored copy.",
"required": [
"id",
"ino",
"libraryId",
"folderId",
"path",
"relPath",
"isFile",
"mtimeMs",
"ctimeMs",
"birthtimeMs",
"addedAt",
"updatedAt",
"isMissing",
"isInvalid",
"mediaType",
"media",
"numFiles",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The item id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"ino": {
"type": "string",
"description": "The item's inode as apps expect one: the edition id again.",
"example": "0"
},
"oldLibraryItemId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"libraryId": {
"type": "string",
"description": "The library the item is listed in.",
"example": "bookclerk-library"
},
"folderId": {
"type": "string",
"description": "The folder id: the library id.",
"example": "bookclerk-library"
},
"path": {
"type": "string",
"description": "A display path: the title.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the title.",
"example": "the-first.m4b"
},
"isFile": {
"type": "boolean",
"description": "Always false: an item is a folder of tracks.",
"example": true
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy last changed, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the item joined the library, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When its record last changed, in epoch milliseconds.",
"example": 1763630000000
},
"isMissing": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"isInvalid": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"mediaType": {
"type": "string",
"description": "Always [`MEDIA_TYPE_BOOK`].",
"example": "book"
},
"media": {
"type": "object",
"description": "The book.",
"required": [
"id",
"metadata",
"tags",
"numTracks",
"numAudioFiles",
"numChapters",
"duration",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The media id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"libraryItemId": {
"type": [
"string",
"null"
],
"description": "The item id, when fetched expanded.",
"example": "li_8f14e45fceea467f"
},
"metadata": {
"type": "object",
"description": "The book's metadata.",
"required": [
"title",
"titleIgnorePrefix",
"authors",
"authorName",
"authorNameLF",
"narrators",
"narratorName",
"series",
"seriesName",
"genres",
"explicit",
"abridged"
],
"properties": {
"title": {
"type": "string",
"description": "The title.",
"example": "The First"
},
"titleIgnorePrefix": {
"type": "string",
"description": "The title for sorting.",
"example": "First, The"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "The subtitle, if any.",
"example": "A Novel"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"description": "An id and a name.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its display name.",
"example": "Ann Author"
}
}
},
"description": "The authors."
},
"authorName": {
"type": "string",
"description": "The authors' names joined with `, `.",
"example": "Ann Author"
},
"authorNameLF": {
"type": "string",
"description": "The authors' names, family name first, joined with `, `.",
"example": "Author, Ann"
},
"narrators": {
"type": "array",
"items": {
"type": "string"
},
"description": "The narrators' names.",
"example": [
"Nia Narrator"
]
},
"narratorName": {
"type": "string",
"description": "The narrators' names joined with `, `.",
"example": "Nia Narrator"
},
"series": {
"type": "array",
"items": {
"type": "object",
"description": "A series an item belongs to, with the item's place in it.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The series name.",
"example": "Ann Author"
},
"sequence": {
"type": [
"string",
"null"
],
"description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
"example": "1"
}
}
},
"description": "The series the book is in."
},
"seriesName": {
"type": "string",
"description": "The series names with the book's place (`Name #2`), joined.",
"example": "The Saga #1"
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"description": "Genres.",
"example": [
"Fantasy"
]
},
"publishedYear": {
"type": [
"string",
"null"
],
"description": "The year of publication, as a string (`\"2019\"`).",
"example": "2024"
},
"publishedDate": {
"type": [
"string",
"null"
],
"description": "The date of publication, if known.",
"example": "2024-03-01"
},
"publisher": {
"type": [
"string",
"null"
],
"description": "The publisher.",
"example": "Example Press"
},
"description": {
"type": [
"string",
"null"
],
"description": "The description, as the library stores it.",
"example": "A short description."
},
"descriptionPlain": {
"type": [
"string",
"null"
],
"description": "The description with markup removed.",
"example": "A short description."
},
"isbn": {
"type": [
"string",
"null"
],
"description": "The ISBN, if known.",
"example": "9780000000002"
},
"asin": {
"type": [
"string",
"null"
],
"description": "The ASIN, if known.",
"example": "B000000000"
},
"language": {
"type": [
"string",
"null"
],
"description": "The language.",
"example": "en-us"
},
"explicit": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"abridged": {
"type": "boolean",
"description": "Whether the edition is abridged.",
"example": false
}
}
},
"coverPath": {
"type": [
"string",
"null"
],
"description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
"example": "/player/api/items/li_8f14e45fceea467f/cover"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags: none.",
"example": []
},
"numTracks": {
"type": "integer",
"format": "int64",
"description": "Tracks in play order.",
"example": 1,
"minimum": 0
},
"numAudioFiles": {
"type": "integer",
"format": "int64",
"description": "Audio files.",
"example": 1,
"minimum": 0
},
"numChapters": {
"type": "integer",
"format": "int64",
"description": "Chapters.",
"example": 0,
"minimum": 0
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds.",
"example": 36000.0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in its audio files.",
"example": 100000,
"minimum": 0
},
"audioFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "An audio file of a book.",
"required": [
"index",
"ino",
"metadata",
"addedAt",
"updatedAt",
"manuallyVerified",
"exclude",
"duration",
"chapters",
"metaTags",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The file's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"trackNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number the file's tags state: not read.",
"example": 1,
"minimum": 0
},
"discNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number the file's tags state: not read.",
"example": null,
"minimum": 0
},
"trackNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number in the file name: not read.",
"example": null,
"minimum": 0
},
"discNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number in the file name: not read.",
"example": null,
"minimum": 0
},
"manuallyVerified": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"exclude": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"error": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"format": {
"type": [
"string",
"null"
],
"description": "The container format, such as `mp4` or `mp3`.",
"example": "MP4A"
},
"duration": {
"type": "number",
"format": "double",
"description": "The file's length in seconds.",
"example": 36000.0
},
"bitRate": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Bits per second, if known.",
"example": 128000,
"minimum": 0
},
"language": {
"type": [
"string",
"null"
],
"description": "The file's language, if known.",
"example": "en-us"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"timeBase": {
"type": [
"string",
"null"
],
"description": "The time base, if known.",
"example": "1/44100"
},
"channels": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Audio channels, if known.",
"example": 2,
"minimum": 0
},
"channelLayout": {
"type": [
"string",
"null"
],
"description": "The channel layout, if known.",
"example": "stereo"
},
"chapters": {
"type": "array",
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "Chapters embedded in the file: none are read."
},
"embeddedCoverArt": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"metaTags": {
"type": "object",
"description": "Tags read from the file: none until the stored media probe reads\nthem."
},
"mimeType": {
"type": "string",
"description": "The file's media type, such as `audio/mp4`.",
"example": "audio/mp4"
}
}
},
"description": "The audio files, when fetched expanded."
},
"chapters": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "The chapters, when fetched expanded."
},
"tracks": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A track with its place in the book.",
"required": [
"index",
"startOffset",
"duration",
"title",
"contentUrl",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The track's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"startOffset": {
"type": "number",
"format": "double",
"description": "Where the track starts in the book, in seconds.",
"example": 0.0
},
"duration": {
"type": "number",
"format": "double",
"description": "The track's length in seconds.",
"example": 36000.0
},
"title": {
"type": "string",
"description": "The track's title: its file name.",
"example": "The First"
},
"contentUrl": {
"type": "string",
"description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
"example": "/player/api/items/li_8f14e45fceea467f/file/0"
},
"mimeType": {
"type": "string",
"description": "The track's media type.",
"example": "audio/mp4"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"metadata": {
"oneOf": [
{
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "The tracks with their place in the book, when fetched expanded."
}
}
},
"numFiles": {
"type": "integer",
"format": "int64",
"description": "Files in the item.",
"example": 1,
"minimum": 0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in all its files.",
"example": 100000,
"minimum": 0
},
"libraryFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A file of an item, in the expanded item's `libraryFiles`.",
"required": [
"ino",
"metadata",
"addedAt",
"updatedAt",
"fileType"
],
"properties": {
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"fileType": {
"type": "string",
"description": "Always `audio`.",
"example": "audio"
}
}
},
"description": "The item's files, when the item is fetched expanded."
},
"userMediaProgress": {
"oneOf": [
{
"type": "object",
"description": "The patron's progress, when the app asked for it.",
"required": [
"id",
"userId",
"libraryItemId",
"mediaItemId",
"mediaItemType",
"duration",
"progress",
"currentTime",
"isFinished",
"hideFromContinueListening",
"lastUpdate",
"startedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The progress id: the item id (one record per patron and item).",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaItemId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"mediaItemType": {
"type": "string",
"description": "Always `book`.",
"example": "book"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds, as last reported.",
"example": 36000.0
},
"progress": {
"type": "number",
"format": "double",
"description": "The share listened, from 0 to 1.",
"example": 0.05
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished it.",
"example": false
},
"hideFromContinueListening": {
"type": "boolean",
"description": "Whether it is hidden from continue listening.",
"example": false
},
"ebookLocation": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"ebookProgress": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Always null.",
"example": null
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When the progress last changed, in epoch milliseconds.",
"example": 1763630000000
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the patron started, in epoch milliseconds.",
"example": 1763620000000
},
"finishedAt": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron finished, in epoch milliseconds.",
"example": null
}
}
},
{
"type": "null"
}
]
},
"seriesSequence": {
"type": [
"string",
"null"
],
"description": "The item's place in a series, on a series' book list.",
"example": "1"
}
}
},
"description": "The author's items, when asked for."
},
"series": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A series of an author's, with the author's items in it.",
"required": [
"id",
"name",
"items"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The series name.",
"example": "Ann Author"
},
"items": {
"type": "array",
"items": {
"type": "object",
"description": "An item: an edition with a stored copy.",
"required": [
"id",
"ino",
"libraryId",
"folderId",
"path",
"relPath",
"isFile",
"mtimeMs",
"ctimeMs",
"birthtimeMs",
"addedAt",
"updatedAt",
"isMissing",
"isInvalid",
"mediaType",
"media",
"numFiles",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The item id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"ino": {
"type": "string",
"description": "The item's inode as apps expect one: the edition id again.",
"example": "0"
},
"oldLibraryItemId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"libraryId": {
"type": "string",
"description": "The library the item is listed in.",
"example": "bookclerk-library"
},
"folderId": {
"type": "string",
"description": "The folder id: the library id.",
"example": "bookclerk-library"
},
"path": {
"type": "string",
"description": "A display path: the title.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the title.",
"example": "the-first.m4b"
},
"isFile": {
"type": "boolean",
"description": "Always false: an item is a folder of tracks.",
"example": true
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy last changed, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the item joined the library, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When its record last changed, in epoch milliseconds.",
"example": 1763630000000
},
"isMissing": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"isInvalid": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"mediaType": {
"type": "string",
"description": "Always [`MEDIA_TYPE_BOOK`].",
"example": "book"
},
"media": {
"type": "object",
"description": "The book.",
"required": [
"id",
"metadata",
"tags",
"numTracks",
"numAudioFiles",
"numChapters",
"duration",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The media id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"libraryItemId": {
"type": [
"string",
"null"
],
"description": "The item id, when fetched expanded.",
"example": "li_8f14e45fceea467f"
},
"metadata": {
"type": "object",
"description": "The book's metadata.",
"required": [
"title",
"titleIgnorePrefix",
"authors",
"authorName",
"authorNameLF",
"narrators",
"narratorName",
"series",
"seriesName",
"genres",
"explicit",
"abridged"
],
"properties": {
"title": {
"type": "string",
"description": "The title.",
"example": "The First"
},
"titleIgnorePrefix": {
"type": "string",
"description": "The title for sorting.",
"example": "First, The"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "The subtitle, if any.",
"example": "A Novel"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"description": "An id and a name.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its display name.",
"example": "Ann Author"
}
}
},
"description": "The authors."
},
"authorName": {
"type": "string",
"description": "The authors' names joined with `, `.",
"example": "Ann Author"
},
"authorNameLF": {
"type": "string",
"description": "The authors' names, family name first, joined with `, `.",
"example": "Author, Ann"
},
"narrators": {
"type": "array",
"items": {
"type": "string"
},
"description": "The narrators' names.",
"example": [
"Nia Narrator"
]
},
"narratorName": {
"type": "string",
"description": "The narrators' names joined with `, `.",
"example": "Nia Narrator"
},
"series": {
"type": "array",
"items": {
"type": "object",
"description": "A series an item belongs to, with the item's place in it.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The series name.",
"example": "Ann Author"
},
"sequence": {
"type": [
"string",
"null"
],
"description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
"example": "1"
}
}
},
"description": "The series the book is in."
},
"seriesName": {
"type": "string",
"description": "The series names with the book's place (`Name #2`), joined.",
"example": "The Saga #1"
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"description": "Genres.",
"example": [
"Fantasy"
]
},
"publishedYear": {
"type": [
"string",
"null"
],
"description": "The year of publication, as a string (`\"2019\"`).",
"example": "2024"
},
"publishedDate": {
"type": [
"string",
"null"
],
"description": "The date of publication, if known.",
"example": "2024-03-01"
},
"publisher": {
"type": [
"string",
"null"
],
"description": "The publisher.",
"example": "Example Press"
},
"description": {
"type": [
"string",
"null"
],
"description": "The description, as the library stores it.",
"example": "A short description."
},
"descriptionPlain": {
"type": [
"string",
"null"
],
"description": "The description with markup removed.",
"example": "A short description."
},
"isbn": {
"type": [
"string",
"null"
],
"description": "The ISBN, if known.",
"example": "9780000000002"
},
"asin": {
"type": [
"string",
"null"
],
"description": "The ASIN, if known.",
"example": "B000000000"
},
"language": {
"type": [
"string",
"null"
],
"description": "The language.",
"example": "en-us"
},
"explicit": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"abridged": {
"type": "boolean",
"description": "Whether the edition is abridged.",
"example": false
}
}
},
"coverPath": {
"type": [
"string",
"null"
],
"description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
"example": "/player/api/items/li_8f14e45fceea467f/cover"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags: none.",
"example": []
},
"numTracks": {
"type": "integer",
"format": "int64",
"description": "Tracks in play order.",
"example": 1,
"minimum": 0
},
"numAudioFiles": {
"type": "integer",
"format": "int64",
"description": "Audio files.",
"example": 1,
"minimum": 0
},
"numChapters": {
"type": "integer",
"format": "int64",
"description": "Chapters.",
"example": 0,
"minimum": 0
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds.",
"example": 36000.0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in its audio files.",
"example": 100000,
"minimum": 0
},
"audioFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "An audio file of a book.",
"required": [
"index",
"ino",
"metadata",
"addedAt",
"updatedAt",
"manuallyVerified",
"exclude",
"duration",
"chapters",
"metaTags",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The file's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"trackNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number the file's tags state: not read.",
"example": 1,
"minimum": 0
},
"discNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number the file's tags state: not read.",
"example": null,
"minimum": 0
},
"trackNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number in the file name: not read.",
"example": null,
"minimum": 0
},
"discNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number in the file name: not read.",
"example": null,
"minimum": 0
},
"manuallyVerified": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"exclude": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"error": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"format": {
"type": [
"string",
"null"
],
"description": "The container format, such as `mp4` or `mp3`.",
"example": "MP4A"
},
"duration": {
"type": "number",
"format": "double",
"description": "The file's length in seconds.",
"example": 36000.0
},
"bitRate": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Bits per second, if known.",
"example": 128000,
"minimum": 0
},
"language": {
"type": [
"string",
"null"
],
"description": "The file's language, if known.",
"example": "en-us"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"timeBase": {
"type": [
"string",
"null"
],
"description": "The time base, if known.",
"example": "1/44100"
},
"channels": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Audio channels, if known.",
"example": 2,
"minimum": 0
},
"channelLayout": {
"type": [
"string",
"null"
],
"description": "The channel layout, if known.",
"example": "stereo"
},
"chapters": {
"type": "array",
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "Chapters embedded in the file: none are read."
},
"embeddedCoverArt": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"metaTags": {
"type": "object",
"description": "Tags read from the file: none until the stored media probe reads\nthem."
},
"mimeType": {
"type": "string",
"description": "The file's media type, such as `audio/mp4`.",
"example": "audio/mp4"
}
}
},
"description": "The audio files, when fetched expanded."
},
"chapters": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "The chapters, when fetched expanded."
},
"tracks": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A track with its place in the book.",
"required": [
"index",
"startOffset",
"duration",
"title",
"contentUrl",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The track's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"startOffset": {
"type": "number",
"format": "double",
"description": "Where the track starts in the book, in seconds.",
"example": 0.0
},
"duration": {
"type": "number",
"format": "double",
"description": "The track's length in seconds.",
"example": 36000.0
},
"title": {
"type": "string",
"description": "The track's title: its file name.",
"example": "The First"
},
"contentUrl": {
"type": "string",
"description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
"example": "/player/api/items/li_8f14e45fceea467f/file/0"
},
"mimeType": {
"type": "string",
"description": "The track's media type.",
"example": "audio/mp4"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"metadata": {
"oneOf": [
{
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "The tracks with their place in the book, when fetched expanded."
}
}
},
"numFiles": {
"type": "integer",
"format": "int64",
"description": "Files in the item.",
"example": 1,
"minimum": 0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in all its files.",
"example": 100000,
"minimum": 0
},
"libraryFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A file of an item, in the expanded item's `libraryFiles`.",
"required": [
"ino",
"metadata",
"addedAt",
"updatedAt",
"fileType"
],
"properties": {
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"fileType": {
"type": "string",
"description": "Always `audio`.",
"example": "audio"
}
}
},
"description": "The item's files, when the item is fetched expanded."
},
"userMediaProgress": {
"oneOf": [
{
"type": "object",
"description": "The patron's progress, when the app asked for it.",
"required": [
"id",
"userId",
"libraryItemId",
"mediaItemId",
"mediaItemType",
"duration",
"progress",
"currentTime",
"isFinished",
"hideFromContinueListening",
"lastUpdate",
"startedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The progress id: the item id (one record per patron and item).",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaItemId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"mediaItemType": {
"type": "string",
"description": "Always `book`.",
"example": "book"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds, as last reported.",
"example": 36000.0
},
"progress": {
"type": "number",
"format": "double",
"description": "The share listened, from 0 to 1.",
"example": 0.05
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished it.",
"example": false
},
"hideFromContinueListening": {
"type": "boolean",
"description": "Whether it is hidden from continue listening.",
"example": false
},
"ebookLocation": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"ebookProgress": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Always null.",
"example": null
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When the progress last changed, in epoch milliseconds.",
"example": 1763630000000
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the patron started, in epoch milliseconds.",
"example": 1763620000000
},
"finishedAt": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron finished, in epoch milliseconds.",
"example": null
}
}
},
{
"type": "null"
}
]
},
"seriesSequence": {
"type": [
"string",
"null"
],
"description": "The item's place in a series, on a series' book list.",
"example": "1"
}
}
},
"description": "The items, in series order."
}
}
},
"description": "The author's series with their items, when asked for."
}
}
},
"description": "Authors."
}
],
"description": "The shelf's entries."
},
"total": {
"type": "integer",
"format": "int64",
"description": "Entries in all.",
"example": 1,
"minimum": 0
}
}
}
}
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 404: No such library.
Not Found
Schema:
A text/plain body: a string.
Status 500: The library could not be read.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Searches the library's items, series, authors and narrators.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
idpathstringrequiredLibrary id.qquerystringrequiredThe search terms.limitqueryinteger (int64)Matches of each kind, default 12.
-
200The matches. Body:
SearchResults(application/json)7 fieldsbookarray ofSearchBookrequiredMatching items.podcastarray of objectrequiredAlways empty.narratorsarray ofNarratorrequiredMatching narrators.tagsarray of objectrequiredAlways empty.genresarray of objectrequiredAlways empty.seriesarray ofSearchSeriesrequiredMatching series.authorsarray ofAuthorrequiredMatching authors.
- 400A query value is out of range, or the terms do not parse. Body: string (
text/plain) - 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 404No such library. Body: string (
text/plain) - 500The library could not be read. Body: string (
text/plain) - 503The search index is being built; retry. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/libraries/<id>/search?q=string' \
-H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/libraries/<id>/search?q=string' `
-Headers @{ Authorization = 'Bearer <playerToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/player/api/libraries/<id>/search?q=string",
headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/libraries/<id>/search?q=string", {
headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/player/api/libraries/<id>/search?q=string")
.header("Authorization", "Bearer <playerToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The matches.
{
"book": [
{
"libraryItem": {
"id": "li_8f14e45fceea467f",
"ino": "0",
"oldLibraryItemId": null,
"libraryId": "bookclerk-library",
"folderId": "bookclerk-library",
"path": "/the-first.m4b",
"relPath": "the-first.m4b",
"isFile": true,
"mtimeMs": 1763600000000,
"ctimeMs": 1763600000000,
"birthtimeMs": 1763600000000,
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"isMissing": false,
"isInvalid": false,
"mediaType": "book",
"media": {
"id": "li_8f14e45fceea467f",
"metadata": {
"title": "The First",
"titleIgnorePrefix": "First, The",
"authors": [],
"authorName": "Ann Author",
"authorNameLF": "Author, Ann",
"narrators": [
"Nia Narrator"
],
"narratorName": "Nia Narrator",
"series": [],
"seriesName": "The Saga #1",
"genres": [
"Fantasy"
],
"explicit": false,
"abridged": false
},
"tags": [],
"numTracks": 1,
"numAudioFiles": 1,
"numChapters": 0,
"duration": 36000.0,
"size": 100000
},
"numFiles": 1,
"size": 100000,
"libraryFiles": [],
"userMediaProgress": {
"id": "li_8f14e45fceea467f",
"userId": "42",
"libraryItemId": "li_8f14e45fceea467f",
"mediaItemId": "li_8f14e45fceea467f",
"mediaItemType": "book",
"duration": 36000.0,
"progress": 0.05,
"currentTime": 1830.5,
"isFinished": false,
"hideFromContinueListening": false,
"lastUpdate": 1763630000000,
"startedAt": 1763620000000
},
"seriesSequence": "1"
}
}
],
"podcast": [],
"narrators": [
{
"id": "li_8f14e45fceea467f",
"name": "Ann Author",
"numBooks": 1
}
],
"tags": [],
"genres": [],
"series": [
{
"series": {
"id": "li_8f14e45fceea467f",
"name": "Ann Author",
"nameIgnorePrefix": "Saga, The",
"description": "A short description.",
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"libraryId": "bookclerk-library",
"books": [],
"progress": {
"libraryItemIds": [
"li_8f14e45fceea467f"
],
"libraryItemIdsFinished": [],
"isFinished": false
}
},
"books": [
{
"id": "li_8f14e45fceea467f",
"ino": "0",
"libraryId": "bookclerk-library",
"folderId": "bookclerk-library",
"path": "/the-first.m4b",
"relPath": "the-first.m4b",
"isFile": true,
"mtimeMs": 1763600000000,
"ctimeMs": 1763600000000,
"birthtimeMs": 1763600000000,
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"isMissing": false,
"isInvalid": false,
"mediaType": "book",
"media": {
"id": "li_8f14e45fceea467f",
"metadata": {
"title": "The First",
"titleIgnorePrefix": "First, The",
"authors": [],
"authorName": "Ann Author",
"authorNameLF": "Author, Ann",
"narrators": [
"Nia Narrator"
],
"narratorName": "Nia Narrator",
"series": [],
"seriesName": "The Saga #1",
"genres": [
"Fantasy"
],
"explicit": false,
"abridged": false
},
"tags": [],
"numTracks": 1,
"numAudioFiles": 1,
"numChapters": 0,
"duration": 36000.0,
"size": 100000
},
"numFiles": 1,
"size": 100000
}
]
}
],
"authors": [
{
"id": "li_8f14e45fceea467f",
"asin": "B000000000",
"name": "Ann Author",
"lastFirst": "Author, Ann",
"description": "A short description.",
"imagePath": null,
"libraryId": "bookclerk-library",
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"numBooks": 1,
"libraryItems": [
{
"id": "li_8f14e45fceea467f",
"ino": "0",
"libraryId": "bookclerk-library",
"folderId": "bookclerk-library",
"path": "/the-first.m4b",
"relPath": "the-first.m4b",
"isFile": true,
"mtimeMs": 1763600000000,
"ctimeMs": 1763600000000,
"birthtimeMs": 1763600000000,
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"isMissing": false,
"isInvalid": false,
"mediaType": "book",
"media": {
"id": "li_8f14e45fceea467f",
"metadata": {
"title": "The First",
"titleIgnorePrefix": "First, The",
"authors": [],
"authorName": "Ann Author",
"authorNameLF": "Author, Ann",
"narrators": [
"Nia Narrator"
],
"narratorName": "Nia Narrator",
"series": [],
"seriesName": "The Saga #1",
"genres": [
"Fantasy"
],
"explicit": false,
"abridged": false
},
"tags": [],
"numTracks": 1,
"numAudioFiles": 1,
"numChapters": 0,
"duration": 36000.0,
"size": 100000
},
"numFiles": 1,
"size": 100000
}
],
"series": [
{
"id": "li_8f14e45fceea467f",
"name": "Ann Author",
"items": []
}
]
}
]
}
Schema:
{
"type": "object",
"description": "`GET /api/libraries/{id}/search`.",
"required": [
"book",
"podcast",
"narrators",
"tags",
"genres",
"series",
"authors"
],
"properties": {
"book": {
"type": "array",
"items": {
"type": "object",
"description": "An item that matched a search.",
"required": [
"libraryItem"
],
"properties": {
"libraryItem": {
"type": "object",
"description": "The item.",
"required": [
"id",
"ino",
"libraryId",
"folderId",
"path",
"relPath",
"isFile",
"mtimeMs",
"ctimeMs",
"birthtimeMs",
"addedAt",
"updatedAt",
"isMissing",
"isInvalid",
"mediaType",
"media",
"numFiles",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The item id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"ino": {
"type": "string",
"description": "The item's inode as apps expect one: the edition id again.",
"example": "0"
},
"oldLibraryItemId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"libraryId": {
"type": "string",
"description": "The library the item is listed in.",
"example": "bookclerk-library"
},
"folderId": {
"type": "string",
"description": "The folder id: the library id.",
"example": "bookclerk-library"
},
"path": {
"type": "string",
"description": "A display path: the title.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the title.",
"example": "the-first.m4b"
},
"isFile": {
"type": "boolean",
"description": "Always false: an item is a folder of tracks.",
"example": true
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy last changed, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the item joined the library, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When its record last changed, in epoch milliseconds.",
"example": 1763630000000
},
"isMissing": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"isInvalid": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"mediaType": {
"type": "string",
"description": "Always [`MEDIA_TYPE_BOOK`].",
"example": "book"
},
"media": {
"type": "object",
"description": "The book.",
"required": [
"id",
"metadata",
"tags",
"numTracks",
"numAudioFiles",
"numChapters",
"duration",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The media id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"libraryItemId": {
"type": [
"string",
"null"
],
"description": "The item id, when fetched expanded.",
"example": "li_8f14e45fceea467f"
},
"metadata": {
"type": "object",
"description": "The book's metadata.",
"required": [
"title",
"titleIgnorePrefix",
"authors",
"authorName",
"authorNameLF",
"narrators",
"narratorName",
"series",
"seriesName",
"genres",
"explicit",
"abridged"
],
"properties": {
"title": {
"type": "string",
"description": "The title.",
"example": "The First"
},
"titleIgnorePrefix": {
"type": "string",
"description": "The title for sorting.",
"example": "First, The"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "The subtitle, if any.",
"example": "A Novel"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"description": "An id and a name.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its display name.",
"example": "Ann Author"
}
}
},
"description": "The authors."
},
"authorName": {
"type": "string",
"description": "The authors' names joined with `, `.",
"example": "Ann Author"
},
"authorNameLF": {
"type": "string",
"description": "The authors' names, family name first, joined with `, `.",
"example": "Author, Ann"
},
"narrators": {
"type": "array",
"items": {
"type": "string"
},
"description": "The narrators' names.",
"example": [
"Nia Narrator"
]
},
"narratorName": {
"type": "string",
"description": "The narrators' names joined with `, `.",
"example": "Nia Narrator"
},
"series": {
"type": "array",
"items": {
"type": "object",
"description": "A series an item belongs to, with the item's place in it.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The series name.",
"example": "Ann Author"
},
"sequence": {
"type": [
"string",
"null"
],
"description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
"example": "1"
}
}
},
"description": "The series the book is in."
},
"seriesName": {
"type": "string",
"description": "The series names with the book's place (`Name #2`), joined.",
"example": "The Saga #1"
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"description": "Genres.",
"example": [
"Fantasy"
]
},
"publishedYear": {
"type": [
"string",
"null"
],
"description": "The year of publication, as a string (`\"2019\"`).",
"example": "2024"
},
"publishedDate": {
"type": [
"string",
"null"
],
"description": "The date of publication, if known.",
"example": "2024-03-01"
},
"publisher": {
"type": [
"string",
"null"
],
"description": "The publisher.",
"example": "Example Press"
},
"description": {
"type": [
"string",
"null"
],
"description": "The description, as the library stores it.",
"example": "A short description."
},
"descriptionPlain": {
"type": [
"string",
"null"
],
"description": "The description with markup removed.",
"example": "A short description."
},
"isbn": {
"type": [
"string",
"null"
],
"description": "The ISBN, if known.",
"example": "9780000000002"
},
"asin": {
"type": [
"string",
"null"
],
"description": "The ASIN, if known.",
"example": "B000000000"
},
"language": {
"type": [
"string",
"null"
],
"description": "The language.",
"example": "en-us"
},
"explicit": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"abridged": {
"type": "boolean",
"description": "Whether the edition is abridged.",
"example": false
}
}
},
"coverPath": {
"type": [
"string",
"null"
],
"description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
"example": "/player/api/items/li_8f14e45fceea467f/cover"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags: none.",
"example": []
},
"numTracks": {
"type": "integer",
"format": "int64",
"description": "Tracks in play order.",
"example": 1,
"minimum": 0
},
"numAudioFiles": {
"type": "integer",
"format": "int64",
"description": "Audio files.",
"example": 1,
"minimum": 0
},
"numChapters": {
"type": "integer",
"format": "int64",
"description": "Chapters.",
"example": 0,
"minimum": 0
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds.",
"example": 36000.0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in its audio files.",
"example": 100000,
"minimum": 0
},
"audioFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "An audio file of a book.",
"required": [
"index",
"ino",
"metadata",
"addedAt",
"updatedAt",
"manuallyVerified",
"exclude",
"duration",
"chapters",
"metaTags",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The file's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"trackNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number the file's tags state: not read.",
"example": 1,
"minimum": 0
},
"discNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number the file's tags state: not read.",
"example": null,
"minimum": 0
},
"trackNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number in the file name: not read.",
"example": null,
"minimum": 0
},
"discNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number in the file name: not read.",
"example": null,
"minimum": 0
},
"manuallyVerified": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"exclude": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"error": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"format": {
"type": [
"string",
"null"
],
"description": "The container format, such as `mp4` or `mp3`.",
"example": "MP4A"
},
"duration": {
"type": "number",
"format": "double",
"description": "The file's length in seconds.",
"example": 36000.0
},
"bitRate": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Bits per second, if known.",
"example": 128000,
"minimum": 0
},
"language": {
"type": [
"string",
"null"
],
"description": "The file's language, if known.",
"example": "en-us"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"timeBase": {
"type": [
"string",
"null"
],
"description": "The time base, if known.",
"example": "1/44100"
},
"channels": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Audio channels, if known.",
"example": 2,
"minimum": 0
},
"channelLayout": {
"type": [
"string",
"null"
],
"description": "The channel layout, if known.",
"example": "stereo"
},
"chapters": {
"type": "array",
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "Chapters embedded in the file: none are read."
},
"embeddedCoverArt": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"metaTags": {
"type": "object",
"description": "Tags read from the file: none until the stored media probe reads\nthem."
},
"mimeType": {
"type": "string",
"description": "The file's media type, such as `audio/mp4`.",
"example": "audio/mp4"
}
}
},
"description": "The audio files, when fetched expanded."
},
"chapters": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "The chapters, when fetched expanded."
},
"tracks": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A track with its place in the book.",
"required": [
"index",
"startOffset",
"duration",
"title",
"contentUrl",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The track's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"startOffset": {
"type": "number",
"format": "double",
"description": "Where the track starts in the book, in seconds.",
"example": 0.0
},
"duration": {
"type": "number",
"format": "double",
"description": "The track's length in seconds.",
"example": 36000.0
},
"title": {
"type": "string",
"description": "The track's title: its file name.",
"example": "The First"
},
"contentUrl": {
"type": "string",
"description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
"example": "/player/api/items/li_8f14e45fceea467f/file/0"
},
"mimeType": {
"type": "string",
"description": "The track's media type.",
"example": "audio/mp4"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"metadata": {
"oneOf": [
{
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "The tracks with their place in the book, when fetched expanded."
}
}
},
"numFiles": {
"type": "integer",
"format": "int64",
"description": "Files in the item.",
"example": 1,
"minimum": 0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in all its files.",
"example": 100000,
"minimum": 0
},
"libraryFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A file of an item, in the expanded item's `libraryFiles`.",
"required": [
"ino",
"metadata",
"addedAt",
"updatedAt",
"fileType"
],
"properties": {
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"fileType": {
"type": "string",
"description": "Always `audio`.",
"example": "audio"
}
}
},
"description": "The item's files, when the item is fetched expanded."
},
"userMediaProgress": {
"oneOf": [
{
"type": "object",
"description": "The patron's progress, when the app asked for it.",
"required": [
"id",
"userId",
"libraryItemId",
"mediaItemId",
"mediaItemType",
"duration",
"progress",
"currentTime",
"isFinished",
"hideFromContinueListening",
"lastUpdate",
"startedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The progress id: the item id (one record per patron and item).",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaItemId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"mediaItemType": {
"type": "string",
"description": "Always `book`.",
"example": "book"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds, as last reported.",
"example": 36000.0
},
"progress": {
"type": "number",
"format": "double",
"description": "The share listened, from 0 to 1.",
"example": 0.05
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished it.",
"example": false
},
"hideFromContinueListening": {
"type": "boolean",
"description": "Whether it is hidden from continue listening.",
"example": false
},
"ebookLocation": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"ebookProgress": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Always null.",
"example": null
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When the progress last changed, in epoch milliseconds.",
"example": 1763630000000
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the patron started, in epoch milliseconds.",
"example": 1763620000000
},
"finishedAt": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron finished, in epoch milliseconds.",
"example": null
}
}
},
{
"type": "null"
}
]
},
"seriesSequence": {
"type": [
"string",
"null"
],
"description": "The item's place in a series, on a series' book list.",
"example": "1"
}
}
}
}
},
"description": "Matching items."
},
"podcast": {
"type": "array",
"items": {
"type": "object"
},
"description": "Always empty.",
"example": []
},
"narrators": {
"type": "array",
"items": {
"type": "object",
"description": "A narrator with how many items they read.",
"required": [
"id",
"name",
"numBooks"
],
"properties": {
"id": {
"type": "string",
"description": "The name in URL-safe base64, as apps filter by it.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The narrator's name.",
"example": "Ann Author"
},
"numBooks": {
"type": "integer",
"format": "int64",
"description": "Items they read that the patron can see.",
"example": 1,
"minimum": 0
}
}
},
"description": "Matching narrators."
},
"tags": {
"type": "array",
"items": {
"type": "object"
},
"description": "Always empty.",
"example": []
},
"genres": {
"type": "array",
"items": {
"type": "object"
},
"description": "Always empty.",
"example": []
},
"series": {
"type": "array",
"items": {
"type": "object",
"description": "A series that matched a search.",
"required": [
"series",
"books"
],
"properties": {
"series": {
"type": "object",
"description": "The series.",
"required": [
"id",
"name",
"nameIgnorePrefix",
"addedAt",
"updatedAt",
"libraryId"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its name.",
"example": "Ann Author"
},
"nameIgnorePrefix": {
"type": "string",
"description": "The name for sorting.",
"example": "Saga, The"
},
"description": {
"type": [
"string",
"null"
],
"description": "Its description: none.",
"example": "A short description."
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the library first saw it, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When it last changed, in epoch milliseconds.",
"example": 1763630000000
},
"libraryId": {
"type": "string",
"description": "The library it is listed in.",
"example": "bookclerk-library"
},
"books": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "An item: an edition with a stored copy.",
"required": [
"id",
"ino",
"libraryId",
"folderId",
"path",
"relPath",
"isFile",
"mtimeMs",
"ctimeMs",
"birthtimeMs",
"addedAt",
"updatedAt",
"isMissing",
"isInvalid",
"mediaType",
"media",
"numFiles",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The item id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"ino": {
"type": "string",
"description": "The item's inode as apps expect one: the edition id again.",
"example": "0"
},
"oldLibraryItemId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"libraryId": {
"type": "string",
"description": "The library the item is listed in.",
"example": "bookclerk-library"
},
"folderId": {
"type": "string",
"description": "The folder id: the library id.",
"example": "bookclerk-library"
},
"path": {
"type": "string",
"description": "A display path: the title.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the title.",
"example": "the-first.m4b"
},
"isFile": {
"type": "boolean",
"description": "Always false: an item is a folder of tracks.",
"example": true
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy last changed, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the item joined the library, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When its record last changed, in epoch milliseconds.",
"example": 1763630000000
},
"isMissing": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"isInvalid": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"mediaType": {
"type": "string",
"description": "Always [`MEDIA_TYPE_BOOK`].",
"example": "book"
},
"media": {
"type": "object",
"description": "The book.",
"required": [
"id",
"metadata",
"tags",
"numTracks",
"numAudioFiles",
"numChapters",
"duration",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The media id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"libraryItemId": {
"type": [
"string",
"null"
],
"description": "The item id, when fetched expanded.",
"example": "li_8f14e45fceea467f"
},
"metadata": {
"type": "object",
"description": "The book's metadata.",
"required": [
"title",
"titleIgnorePrefix",
"authors",
"authorName",
"authorNameLF",
"narrators",
"narratorName",
"series",
"seriesName",
"genres",
"explicit",
"abridged"
],
"properties": {
"title": {
"type": "string",
"description": "The title.",
"example": "The First"
},
"titleIgnorePrefix": {
"type": "string",
"description": "The title for sorting.",
"example": "First, The"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "The subtitle, if any.",
"example": "A Novel"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"description": "An id and a name.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its display name.",
"example": "Ann Author"
}
}
},
"description": "The authors."
},
"authorName": {
"type": "string",
"description": "The authors' names joined with `, `.",
"example": "Ann Author"
},
"authorNameLF": {
"type": "string",
"description": "The authors' names, family name first, joined with `, `.",
"example": "Author, Ann"
},
"narrators": {
"type": "array",
"items": {
"type": "string"
},
"description": "The narrators' names.",
"example": [
"Nia Narrator"
]
},
"narratorName": {
"type": "string",
"description": "The narrators' names joined with `, `.",
"example": "Nia Narrator"
},
"series": {
"type": "array",
"items": {
"type": "object",
"description": "A series an item belongs to, with the item's place in it.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The series name.",
"example": "Ann Author"
},
"sequence": {
"type": [
"string",
"null"
],
"description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
"example": "1"
}
}
},
"description": "The series the book is in."
},
"seriesName": {
"type": "string",
"description": "The series names with the book's place (`Name #2`), joined.",
"example": "The Saga #1"
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"description": "Genres.",
"example": [
"Fantasy"
]
},
"publishedYear": {
"type": [
"string",
"null"
],
"description": "The year of publication, as a string (`\"2019\"`).",
"example": "2024"
},
"publishedDate": {
"type": [
"string",
"null"
],
"description": "The date of publication, if known.",
"example": "2024-03-01"
},
"publisher": {
"type": [
"string",
"null"
],
"description": "The publisher.",
"example": "Example Press"
},
"description": {
"type": [
"string",
"null"
],
"description": "The description, as the library stores it.",
"example": "A short description."
},
"descriptionPlain": {
"type": [
"string",
"null"
],
"description": "The description with markup removed.",
"example": "A short description."
},
"isbn": {
"type": [
"string",
"null"
],
"description": "The ISBN, if known.",
"example": "9780000000002"
},
"asin": {
"type": [
"string",
"null"
],
"description": "The ASIN, if known.",
"example": "B000000000"
},
"language": {
"type": [
"string",
"null"
],
"description": "The language.",
"example": "en-us"
},
"explicit": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"abridged": {
"type": "boolean",
"description": "Whether the edition is abridged.",
"example": false
}
}
},
"coverPath": {
"type": [
"string",
"null"
],
"description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
"example": "/player/api/items/li_8f14e45fceea467f/cover"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags: none.",
"example": []
},
"numTracks": {
"type": "integer",
"format": "int64",
"description": "Tracks in play order.",
"example": 1,
"minimum": 0
},
"numAudioFiles": {
"type": "integer",
"format": "int64",
"description": "Audio files.",
"example": 1,
"minimum": 0
},
"numChapters": {
"type": "integer",
"format": "int64",
"description": "Chapters.",
"example": 0,
"minimum": 0
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds.",
"example": 36000.0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in its audio files.",
"example": 100000,
"minimum": 0
},
"audioFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "An audio file of a book.",
"required": [
"index",
"ino",
"metadata",
"addedAt",
"updatedAt",
"manuallyVerified",
"exclude",
"duration",
"chapters",
"metaTags",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The file's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"trackNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number the file's tags state: not read.",
"example": 1,
"minimum": 0
},
"discNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number the file's tags state: not read.",
"example": null,
"minimum": 0
},
"trackNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number in the file name: not read.",
"example": null,
"minimum": 0
},
"discNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number in the file name: not read.",
"example": null,
"minimum": 0
},
"manuallyVerified": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"exclude": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"error": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"format": {
"type": [
"string",
"null"
],
"description": "The container format, such as `mp4` or `mp3`.",
"example": "MP4A"
},
"duration": {
"type": "number",
"format": "double",
"description": "The file's length in seconds.",
"example": 36000.0
},
"bitRate": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Bits per second, if known.",
"example": 128000,
"minimum": 0
},
"language": {
"type": [
"string",
"null"
],
"description": "The file's language, if known.",
"example": "en-us"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"timeBase": {
"type": [
"string",
"null"
],
"description": "The time base, if known.",
"example": "1/44100"
},
"channels": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Audio channels, if known.",
"example": 2,
"minimum": 0
},
"channelLayout": {
"type": [
"string",
"null"
],
"description": "The channel layout, if known.",
"example": "stereo"
},
"chapters": {
"type": "array",
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "Chapters embedded in the file: none are read."
},
"embeddedCoverArt": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"metaTags": {
"type": "object",
"description": "Tags read from the file: none until the stored media probe reads\nthem."
},
"mimeType": {
"type": "string",
"description": "The file's media type, such as `audio/mp4`.",
"example": "audio/mp4"
}
}
},
"description": "The audio files, when fetched expanded."
},
"chapters": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "The chapters, when fetched expanded."
},
"tracks": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A track with its place in the book.",
"required": [
"index",
"startOffset",
"duration",
"title",
"contentUrl",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The track's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"startOffset": {
"type": "number",
"format": "double",
"description": "Where the track starts in the book, in seconds.",
"example": 0.0
},
"duration": {
"type": "number",
"format": "double",
"description": "The track's length in seconds.",
"example": 36000.0
},
"title": {
"type": "string",
"description": "The track's title: its file name.",
"example": "The First"
},
"contentUrl": {
"type": "string",
"description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
"example": "/player/api/items/li_8f14e45fceea467f/file/0"
},
"mimeType": {
"type": "string",
"description": "The track's media type.",
"example": "audio/mp4"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"metadata": {
"oneOf": [
{
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "The tracks with their place in the book, when fetched expanded."
}
}
},
"numFiles": {
"type": "integer",
"format": "int64",
"description": "Files in the item.",
"example": 1,
"minimum": 0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in all its files.",
"example": 100000,
"minimum": 0
},
"libraryFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A file of an item, in the expanded item's `libraryFiles`.",
"required": [
"ino",
"metadata",
"addedAt",
"updatedAt",
"fileType"
],
"properties": {
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"fileType": {
"type": "string",
"description": "Always `audio`.",
"example": "audio"
}
}
},
"description": "The item's files, when the item is fetched expanded."
},
"userMediaProgress": {
"oneOf": [
{
"type": "object",
"description": "The patron's progress, when the app asked for it.",
"required": [
"id",
"userId",
"libraryItemId",
"mediaItemId",
"mediaItemType",
"duration",
"progress",
"currentTime",
"isFinished",
"hideFromContinueListening",
"lastUpdate",
"startedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The progress id: the item id (one record per patron and item).",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaItemId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"mediaItemType": {
"type": "string",
"description": "Always `book`.",
"example": "book"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds, as last reported.",
"example": 36000.0
},
"progress": {
"type": "number",
"format": "double",
"description": "The share listened, from 0 to 1.",
"example": 0.05
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished it.",
"example": false
},
"hideFromContinueListening": {
"type": "boolean",
"description": "Whether it is hidden from continue listening.",
"example": false
},
"ebookLocation": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"ebookProgress": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Always null.",
"example": null
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When the progress last changed, in epoch milliseconds.",
"example": 1763630000000
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the patron started, in epoch milliseconds.",
"example": 1763620000000
},
"finishedAt": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron finished, in epoch milliseconds.",
"example": null
}
}
},
{
"type": "null"
}
]
},
"seriesSequence": {
"type": [
"string",
"null"
],
"description": "The item's place in a series, on a series' book list.",
"example": "1"
}
}
},
"description": "Its items in series order, on lists."
},
"progress": {
"oneOf": [
{
"type": "object",
"description": "The patron's progress through it, when asked for.",
"required": [
"libraryItemIds",
"libraryItemIdsFinished",
"isFinished"
],
"properties": {
"libraryItemIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "The series' items, by id.",
"example": [
"li_8f14e45fceea467f"
]
},
"libraryItemIdsFinished": {
"type": "array",
"items": {
"type": "string"
},
"description": "Those the patron finished.",
"example": []
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished every one.",
"example": false
}
}
},
{
"type": "null"
}
]
}
}
},
"books": {
"type": "array",
"items": {
"type": "object",
"description": "An item: an edition with a stored copy.",
"required": [
"id",
"ino",
"libraryId",
"folderId",
"path",
"relPath",
"isFile",
"mtimeMs",
"ctimeMs",
"birthtimeMs",
"addedAt",
"updatedAt",
"isMissing",
"isInvalid",
"mediaType",
"media",
"numFiles",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The item id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"ino": {
"type": "string",
"description": "The item's inode as apps expect one: the edition id again.",
"example": "0"
},
"oldLibraryItemId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"libraryId": {
"type": "string",
"description": "The library the item is listed in.",
"example": "bookclerk-library"
},
"folderId": {
"type": "string",
"description": "The folder id: the library id.",
"example": "bookclerk-library"
},
"path": {
"type": "string",
"description": "A display path: the title.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the title.",
"example": "the-first.m4b"
},
"isFile": {
"type": "boolean",
"description": "Always false: an item is a folder of tracks.",
"example": true
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy last changed, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the item joined the library, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When its record last changed, in epoch milliseconds.",
"example": 1763630000000
},
"isMissing": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"isInvalid": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"mediaType": {
"type": "string",
"description": "Always [`MEDIA_TYPE_BOOK`].",
"example": "book"
},
"media": {
"type": "object",
"description": "The book.",
"required": [
"id",
"metadata",
"tags",
"numTracks",
"numAudioFiles",
"numChapters",
"duration",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The media id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"libraryItemId": {
"type": [
"string",
"null"
],
"description": "The item id, when fetched expanded.",
"example": "li_8f14e45fceea467f"
},
"metadata": {
"type": "object",
"description": "The book's metadata.",
"required": [
"title",
"titleIgnorePrefix",
"authors",
"authorName",
"authorNameLF",
"narrators",
"narratorName",
"series",
"seriesName",
"genres",
"explicit",
"abridged"
],
"properties": {
"title": {
"type": "string",
"description": "The title.",
"example": "The First"
},
"titleIgnorePrefix": {
"type": "string",
"description": "The title for sorting.",
"example": "First, The"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "The subtitle, if any.",
"example": "A Novel"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"description": "An id and a name.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its display name.",
"example": "Ann Author"
}
}
},
"description": "The authors."
},
"authorName": {
"type": "string",
"description": "The authors' names joined with `, `.",
"example": "Ann Author"
},
"authorNameLF": {
"type": "string",
"description": "The authors' names, family name first, joined with `, `.",
"example": "Author, Ann"
},
"narrators": {
"type": "array",
"items": {
"type": "string"
},
"description": "The narrators' names.",
"example": [
"Nia Narrator"
]
},
"narratorName": {
"type": "string",
"description": "The narrators' names joined with `, `.",
"example": "Nia Narrator"
},
"series": {
"type": "array",
"items": {
"type": "object",
"description": "A series an item belongs to, with the item's place in it.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The series name.",
"example": "Ann Author"
},
"sequence": {
"type": [
"string",
"null"
],
"description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
"example": "1"
}
}
},
"description": "The series the book is in."
},
"seriesName": {
"type": "string",
"description": "The series names with the book's place (`Name #2`), joined.",
"example": "The Saga #1"
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"description": "Genres.",
"example": [
"Fantasy"
]
},
"publishedYear": {
"type": [
"string",
"null"
],
"description": "The year of publication, as a string (`\"2019\"`).",
"example": "2024"
},
"publishedDate": {
"type": [
"string",
"null"
],
"description": "The date of publication, if known.",
"example": "2024-03-01"
},
"publisher": {
"type": [
"string",
"null"
],
"description": "The publisher.",
"example": "Example Press"
},
"description": {
"type": [
"string",
"null"
],
"description": "The description, as the library stores it.",
"example": "A short description."
},
"descriptionPlain": {
"type": [
"string",
"null"
],
"description": "The description with markup removed.",
"example": "A short description."
},
"isbn": {
"type": [
"string",
"null"
],
"description": "The ISBN, if known.",
"example": "9780000000002"
},
"asin": {
"type": [
"string",
"null"
],
"description": "The ASIN, if known.",
"example": "B000000000"
},
"language": {
"type": [
"string",
"null"
],
"description": "The language.",
"example": "en-us"
},
"explicit": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"abridged": {
"type": "boolean",
"description": "Whether the edition is abridged.",
"example": false
}
}
},
"coverPath": {
"type": [
"string",
"null"
],
"description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
"example": "/player/api/items/li_8f14e45fceea467f/cover"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags: none.",
"example": []
},
"numTracks": {
"type": "integer",
"format": "int64",
"description": "Tracks in play order.",
"example": 1,
"minimum": 0
},
"numAudioFiles": {
"type": "integer",
"format": "int64",
"description": "Audio files.",
"example": 1,
"minimum": 0
},
"numChapters": {
"type": "integer",
"format": "int64",
"description": "Chapters.",
"example": 0,
"minimum": 0
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds.",
"example": 36000.0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in its audio files.",
"example": 100000,
"minimum": 0
},
"audioFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "An audio file of a book.",
"required": [
"index",
"ino",
"metadata",
"addedAt",
"updatedAt",
"manuallyVerified",
"exclude",
"duration",
"chapters",
"metaTags",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The file's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"trackNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number the file's tags state: not read.",
"example": 1,
"minimum": 0
},
"discNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number the file's tags state: not read.",
"example": null,
"minimum": 0
},
"trackNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number in the file name: not read.",
"example": null,
"minimum": 0
},
"discNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number in the file name: not read.",
"example": null,
"minimum": 0
},
"manuallyVerified": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"exclude": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"error": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"format": {
"type": [
"string",
"null"
],
"description": "The container format, such as `mp4` or `mp3`.",
"example": "MP4A"
},
"duration": {
"type": "number",
"format": "double",
"description": "The file's length in seconds.",
"example": 36000.0
},
"bitRate": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Bits per second, if known.",
"example": 128000,
"minimum": 0
},
"language": {
"type": [
"string",
"null"
],
"description": "The file's language, if known.",
"example": "en-us"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"timeBase": {
"type": [
"string",
"null"
],
"description": "The time base, if known.",
"example": "1/44100"
},
"channels": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Audio channels, if known.",
"example": 2,
"minimum": 0
},
"channelLayout": {
"type": [
"string",
"null"
],
"description": "The channel layout, if known.",
"example": "stereo"
},
"chapters": {
"type": "array",
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "Chapters embedded in the file: none are read."
},
"embeddedCoverArt": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"metaTags": {
"type": "object",
"description": "Tags read from the file: none until the stored media probe reads\nthem."
},
"mimeType": {
"type": "string",
"description": "The file's media type, such as `audio/mp4`.",
"example": "audio/mp4"
}
}
},
"description": "The audio files, when fetched expanded."
},
"chapters": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "The chapters, when fetched expanded."
},
"tracks": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A track with its place in the book.",
"required": [
"index",
"startOffset",
"duration",
"title",
"contentUrl",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The track's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"startOffset": {
"type": "number",
"format": "double",
"description": "Where the track starts in the book, in seconds.",
"example": 0.0
},
"duration": {
"type": "number",
"format": "double",
"description": "The track's length in seconds.",
"example": 36000.0
},
"title": {
"type": "string",
"description": "The track's title: its file name.",
"example": "The First"
},
"contentUrl": {
"type": "string",
"description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
"example": "/player/api/items/li_8f14e45fceea467f/file/0"
},
"mimeType": {
"type": "string",
"description": "The track's media type.",
"example": "audio/mp4"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"metadata": {
"oneOf": [
{
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "The tracks with their place in the book, when fetched expanded."
}
}
},
"numFiles": {
"type": "integer",
"format": "int64",
"description": "Files in the item.",
"example": 1,
"minimum": 0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in all its files.",
"example": 100000,
"minimum": 0
},
"libraryFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A file of an item, in the expanded item's `libraryFiles`.",
"required": [
"ino",
"metadata",
"addedAt",
"updatedAt",
"fileType"
],
"properties": {
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"fileType": {
"type": "string",
"description": "Always `audio`.",
"example": "audio"
}
}
},
"description": "The item's files, when the item is fetched expanded."
},
"userMediaProgress": {
"oneOf": [
{
"type": "object",
"description": "The patron's progress, when the app asked for it.",
"required": [
"id",
"userId",
"libraryItemId",
"mediaItemId",
"mediaItemType",
"duration",
"progress",
"currentTime",
"isFinished",
"hideFromContinueListening",
"lastUpdate",
"startedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The progress id: the item id (one record per patron and item).",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaItemId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"mediaItemType": {
"type": "string",
"description": "Always `book`.",
"example": "book"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds, as last reported.",
"example": 36000.0
},
"progress": {
"type": "number",
"format": "double",
"description": "The share listened, from 0 to 1.",
"example": 0.05
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished it.",
"example": false
},
"hideFromContinueListening": {
"type": "boolean",
"description": "Whether it is hidden from continue listening.",
"example": false
},
"ebookLocation": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"ebookProgress": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Always null.",
"example": null
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When the progress last changed, in epoch milliseconds.",
"example": 1763630000000
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the patron started, in epoch milliseconds.",
"example": 1763620000000
},
"finishedAt": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron finished, in epoch milliseconds.",
"example": null
}
}
},
{
"type": "null"
}
]
},
"seriesSequence": {
"type": [
"string",
"null"
],
"description": "The item's place in a series, on a series' book list.",
"example": "1"
}
}
},
"description": "Its items."
}
}
},
"description": "Matching series."
},
"authors": {
"type": "array",
"items": {
"type": "object",
"description": "An author.",
"required": [
"id",
"name",
"lastFirst",
"libraryId",
"addedAt",
"updatedAt",
"numBooks"
],
"properties": {
"id": {
"type": "string",
"description": "The contributor id.",
"example": "li_8f14e45fceea467f"
},
"asin": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": "B000000000"
},
"name": {
"type": "string",
"description": "The author's name.",
"example": "Ann Author"
},
"lastFirst": {
"type": "string",
"description": "The name family name first.",
"example": "Author, Ann"
},
"description": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": "A short description."
},
"imagePath": {
"type": [
"string",
"null"
],
"description": "Always null: no author images.",
"example": null
},
"libraryId": {
"type": "string",
"description": "The library it is listed in.",
"example": "bookclerk-library"
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the library first saw the author, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the record last changed, in epoch milliseconds.",
"example": 1763630000000
},
"numBooks": {
"type": "integer",
"format": "int64",
"description": "Items by the author the patron can see.",
"example": 1,
"minimum": 0
},
"libraryItems": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "An item: an edition with a stored copy.",
"required": [
"id",
"ino",
"libraryId",
"folderId",
"path",
"relPath",
"isFile",
"mtimeMs",
"ctimeMs",
"birthtimeMs",
"addedAt",
"updatedAt",
"isMissing",
"isInvalid",
"mediaType",
"media",
"numFiles",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The item id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"ino": {
"type": "string",
"description": "The item's inode as apps expect one: the edition id again.",
"example": "0"
},
"oldLibraryItemId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"libraryId": {
"type": "string",
"description": "The library the item is listed in.",
"example": "bookclerk-library"
},
"folderId": {
"type": "string",
"description": "The folder id: the library id.",
"example": "bookclerk-library"
},
"path": {
"type": "string",
"description": "A display path: the title.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the title.",
"example": "the-first.m4b"
},
"isFile": {
"type": "boolean",
"description": "Always false: an item is a folder of tracks.",
"example": true
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy last changed, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the item joined the library, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When its record last changed, in epoch milliseconds.",
"example": 1763630000000
},
"isMissing": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"isInvalid": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"mediaType": {
"type": "string",
"description": "Always [`MEDIA_TYPE_BOOK`].",
"example": "book"
},
"media": {
"type": "object",
"description": "The book.",
"required": [
"id",
"metadata",
"tags",
"numTracks",
"numAudioFiles",
"numChapters",
"duration",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The media id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"libraryItemId": {
"type": [
"string",
"null"
],
"description": "The item id, when fetched expanded.",
"example": "li_8f14e45fceea467f"
},
"metadata": {
"type": "object",
"description": "The book's metadata.",
"required": [
"title",
"titleIgnorePrefix",
"authors",
"authorName",
"authorNameLF",
"narrators",
"narratorName",
"series",
"seriesName",
"genres",
"explicit",
"abridged"
],
"properties": {
"title": {
"type": "string",
"description": "The title.",
"example": "The First"
},
"titleIgnorePrefix": {
"type": "string",
"description": "The title for sorting.",
"example": "First, The"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "The subtitle, if any.",
"example": "A Novel"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"description": "An id and a name.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its display name.",
"example": "Ann Author"
}
}
},
"description": "The authors."
},
"authorName": {
"type": "string",
"description": "The authors' names joined with `, `.",
"example": "Ann Author"
},
"authorNameLF": {
"type": "string",
"description": "The authors' names, family name first, joined with `, `.",
"example": "Author, Ann"
},
"narrators": {
"type": "array",
"items": {
"type": "string"
},
"description": "The narrators' names.",
"example": [
"Nia Narrator"
]
},
"narratorName": {
"type": "string",
"description": "The narrators' names joined with `, `.",
"example": "Nia Narrator"
},
"series": {
"type": "array",
"items": {
"type": "object",
"description": "A series an item belongs to, with the item's place in it.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The series name.",
"example": "Ann Author"
},
"sequence": {
"type": [
"string",
"null"
],
"description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
"example": "1"
}
}
},
"description": "The series the book is in."
},
"seriesName": {
"type": "string",
"description": "The series names with the book's place (`Name #2`), joined.",
"example": "The Saga #1"
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"description": "Genres.",
"example": [
"Fantasy"
]
},
"publishedYear": {
"type": [
"string",
"null"
],
"description": "The year of publication, as a string (`\"2019\"`).",
"example": "2024"
},
"publishedDate": {
"type": [
"string",
"null"
],
"description": "The date of publication, if known.",
"example": "2024-03-01"
},
"publisher": {
"type": [
"string",
"null"
],
"description": "The publisher.",
"example": "Example Press"
},
"description": {
"type": [
"string",
"null"
],
"description": "The description, as the library stores it.",
"example": "A short description."
},
"descriptionPlain": {
"type": [
"string",
"null"
],
"description": "The description with markup removed.",
"example": "A short description."
},
"isbn": {
"type": [
"string",
"null"
],
"description": "The ISBN, if known.",
"example": "9780000000002"
},
"asin": {
"type": [
"string",
"null"
],
"description": "The ASIN, if known.",
"example": "B000000000"
},
"language": {
"type": [
"string",
"null"
],
"description": "The language.",
"example": "en-us"
},
"explicit": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"abridged": {
"type": "boolean",
"description": "Whether the edition is abridged.",
"example": false
}
}
},
"coverPath": {
"type": [
"string",
"null"
],
"description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
"example": "/player/api/items/li_8f14e45fceea467f/cover"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags: none.",
"example": []
},
"numTracks": {
"type": "integer",
"format": "int64",
"description": "Tracks in play order.",
"example": 1,
"minimum": 0
},
"numAudioFiles": {
"type": "integer",
"format": "int64",
"description": "Audio files.",
"example": 1,
"minimum": 0
},
"numChapters": {
"type": "integer",
"format": "int64",
"description": "Chapters.",
"example": 0,
"minimum": 0
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds.",
"example": 36000.0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in its audio files.",
"example": 100000,
"minimum": 0
},
"audioFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "An audio file of a book.",
"required": [
"index",
"ino",
"metadata",
"addedAt",
"updatedAt",
"manuallyVerified",
"exclude",
"duration",
"chapters",
"metaTags",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The file's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"trackNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number the file's tags state: not read.",
"example": 1,
"minimum": 0
},
"discNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number the file's tags state: not read.",
"example": null,
"minimum": 0
},
"trackNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number in the file name: not read.",
"example": null,
"minimum": 0
},
"discNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number in the file name: not read.",
"example": null,
"minimum": 0
},
"manuallyVerified": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"exclude": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"error": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"format": {
"type": [
"string",
"null"
],
"description": "The container format, such as `mp4` or `mp3`.",
"example": "MP4A"
},
"duration": {
"type": "number",
"format": "double",
"description": "The file's length in seconds.",
"example": 36000.0
},
"bitRate": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Bits per second, if known.",
"example": 128000,
"minimum": 0
},
"language": {
"type": [
"string",
"null"
],
"description": "The file's language, if known.",
"example": "en-us"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"timeBase": {
"type": [
"string",
"null"
],
"description": "The time base, if known.",
"example": "1/44100"
},
"channels": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Audio channels, if known.",
"example": 2,
"minimum": 0
},
"channelLayout": {
"type": [
"string",
"null"
],
"description": "The channel layout, if known.",
"example": "stereo"
},
"chapters": {
"type": "array",
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "Chapters embedded in the file: none are read."
},
"embeddedCoverArt": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"metaTags": {
"type": "object",
"description": "Tags read from the file: none until the stored media probe reads\nthem."
},
"mimeType": {
"type": "string",
"description": "The file's media type, such as `audio/mp4`.",
"example": "audio/mp4"
}
}
},
"description": "The audio files, when fetched expanded."
},
"chapters": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "The chapters, when fetched expanded."
},
"tracks": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A track with its place in the book.",
"required": [
"index",
"startOffset",
"duration",
"title",
"contentUrl",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The track's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"startOffset": {
"type": "number",
"format": "double",
"description": "Where the track starts in the book, in seconds.",
"example": 0.0
},
"duration": {
"type": "number",
"format": "double",
"description": "The track's length in seconds.",
"example": 36000.0
},
"title": {
"type": "string",
"description": "The track's title: its file name.",
"example": "The First"
},
"contentUrl": {
"type": "string",
"description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
"example": "/player/api/items/li_8f14e45fceea467f/file/0"
},
"mimeType": {
"type": "string",
"description": "The track's media type.",
"example": "audio/mp4"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"metadata": {
"oneOf": [
{
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "The tracks with their place in the book, when fetched expanded."
}
}
},
"numFiles": {
"type": "integer",
"format": "int64",
"description": "Files in the item.",
"example": 1,
"minimum": 0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in all its files.",
"example": 100000,
"minimum": 0
},
"libraryFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A file of an item, in the expanded item's `libraryFiles`.",
"required": [
"ino",
"metadata",
"addedAt",
"updatedAt",
"fileType"
],
"properties": {
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"fileType": {
"type": "string",
"description": "Always `audio`.",
"example": "audio"
}
}
},
"description": "The item's files, when the item is fetched expanded."
},
"userMediaProgress": {
"oneOf": [
{
"type": "object",
"description": "The patron's progress, when the app asked for it.",
"required": [
"id",
"userId",
"libraryItemId",
"mediaItemId",
"mediaItemType",
"duration",
"progress",
"currentTime",
"isFinished",
"hideFromContinueListening",
"lastUpdate",
"startedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The progress id: the item id (one record per patron and item).",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaItemId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"mediaItemType": {
"type": "string",
"description": "Always `book`.",
"example": "book"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds, as last reported.",
"example": 36000.0
},
"progress": {
"type": "number",
"format": "double",
"description": "The share listened, from 0 to 1.",
"example": 0.05
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished it.",
"example": false
},
"hideFromContinueListening": {
"type": "boolean",
"description": "Whether it is hidden from continue listening.",
"example": false
},
"ebookLocation": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"ebookProgress": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Always null.",
"example": null
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When the progress last changed, in epoch milliseconds.",
"example": 1763630000000
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the patron started, in epoch milliseconds.",
"example": 1763620000000
},
"finishedAt": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron finished, in epoch milliseconds.",
"example": null
}
}
},
{
"type": "null"
}
]
},
"seriesSequence": {
"type": [
"string",
"null"
],
"description": "The item's place in a series, on a series' book list.",
"example": "1"
}
}
},
"description": "The author's items, when asked for."
},
"series": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A series of an author's, with the author's items in it.",
"required": [
"id",
"name",
"items"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The series name.",
"example": "Ann Author"
},
"items": {
"type": "array",
"items": {
"type": "object",
"description": "An item: an edition with a stored copy.",
"required": [
"id",
"ino",
"libraryId",
"folderId",
"path",
"relPath",
"isFile",
"mtimeMs",
"ctimeMs",
"birthtimeMs",
"addedAt",
"updatedAt",
"isMissing",
"isInvalid",
"mediaType",
"media",
"numFiles",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The item id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"ino": {
"type": "string",
"description": "The item's inode as apps expect one: the edition id again.",
"example": "0"
},
"oldLibraryItemId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"libraryId": {
"type": "string",
"description": "The library the item is listed in.",
"example": "bookclerk-library"
},
"folderId": {
"type": "string",
"description": "The folder id: the library id.",
"example": "bookclerk-library"
},
"path": {
"type": "string",
"description": "A display path: the title.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the title.",
"example": "the-first.m4b"
},
"isFile": {
"type": "boolean",
"description": "Always false: an item is a folder of tracks.",
"example": true
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy last changed, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the item joined the library, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When its record last changed, in epoch milliseconds.",
"example": 1763630000000
},
"isMissing": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"isInvalid": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"mediaType": {
"type": "string",
"description": "Always [`MEDIA_TYPE_BOOK`].",
"example": "book"
},
"media": {
"type": "object",
"description": "The book.",
"required": [
"id",
"metadata",
"tags",
"numTracks",
"numAudioFiles",
"numChapters",
"duration",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The media id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"libraryItemId": {
"type": [
"string",
"null"
],
"description": "The item id, when fetched expanded.",
"example": "li_8f14e45fceea467f"
},
"metadata": {
"type": "object",
"description": "The book's metadata.",
"required": [
"title",
"titleIgnorePrefix",
"authors",
"authorName",
"authorNameLF",
"narrators",
"narratorName",
"series",
"seriesName",
"genres",
"explicit",
"abridged"
],
"properties": {
"title": {
"type": "string",
"description": "The title.",
"example": "The First"
},
"titleIgnorePrefix": {
"type": "string",
"description": "The title for sorting.",
"example": "First, The"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "The subtitle, if any.",
"example": "A Novel"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"description": "An id and a name.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its display name.",
"example": "Ann Author"
}
}
},
"description": "The authors."
},
"authorName": {
"type": "string",
"description": "The authors' names joined with `, `.",
"example": "Ann Author"
},
"authorNameLF": {
"type": "string",
"description": "The authors' names, family name first, joined with `, `.",
"example": "Author, Ann"
},
"narrators": {
"type": "array",
"items": {
"type": "string"
},
"description": "The narrators' names.",
"example": [
"Nia Narrator"
]
},
"narratorName": {
"type": "string",
"description": "The narrators' names joined with `, `.",
"example": "Nia Narrator"
},
"series": {
"type": "array",
"items": {
"type": "object",
"description": "A series an item belongs to, with the item's place in it.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The series name.",
"example": "Ann Author"
},
"sequence": {
"type": [
"string",
"null"
],
"description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
"example": "1"
}
}
},
"description": "The series the book is in."
},
"seriesName": {
"type": "string",
"description": "The series names with the book's place (`Name #2`), joined.",
"example": "The Saga #1"
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"description": "Genres.",
"example": [
"Fantasy"
]
},
"publishedYear": {
"type": [
"string",
"null"
],
"description": "The year of publication, as a string (`\"2019\"`).",
"example": "2024"
},
"publishedDate": {
"type": [
"string",
"null"
],
"description": "The date of publication, if known.",
"example": "2024-03-01"
},
"publisher": {
"type": [
"string",
"null"
],
"description": "The publisher.",
"example": "Example Press"
},
"description": {
"type": [
"string",
"null"
],
"description": "The description, as the library stores it.",
"example": "A short description."
},
"descriptionPlain": {
"type": [
"string",
"null"
],
"description": "The description with markup removed.",
"example": "A short description."
},
"isbn": {
"type": [
"string",
"null"
],
"description": "The ISBN, if known.",
"example": "9780000000002"
},
"asin": {
"type": [
"string",
"null"
],
"description": "The ASIN, if known.",
"example": "B000000000"
},
"language": {
"type": [
"string",
"null"
],
"description": "The language.",
"example": "en-us"
},
"explicit": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"abridged": {
"type": "boolean",
"description": "Whether the edition is abridged.",
"example": false
}
}
},
"coverPath": {
"type": [
"string",
"null"
],
"description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
"example": "/player/api/items/li_8f14e45fceea467f/cover"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags: none.",
"example": []
},
"numTracks": {
"type": "integer",
"format": "int64",
"description": "Tracks in play order.",
"example": 1,
"minimum": 0
},
"numAudioFiles": {
"type": "integer",
"format": "int64",
"description": "Audio files.",
"example": 1,
"minimum": 0
},
"numChapters": {
"type": "integer",
"format": "int64",
"description": "Chapters.",
"example": 0,
"minimum": 0
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds.",
"example": 36000.0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in its audio files.",
"example": 100000,
"minimum": 0
},
"audioFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "An audio file of a book.",
"required": [
"index",
"ino",
"metadata",
"addedAt",
"updatedAt",
"manuallyVerified",
"exclude",
"duration",
"chapters",
"metaTags",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The file's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"trackNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number the file's tags state: not read.",
"example": 1,
"minimum": 0
},
"discNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number the file's tags state: not read.",
"example": null,
"minimum": 0
},
"trackNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number in the file name: not read.",
"example": null,
"minimum": 0
},
"discNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number in the file name: not read.",
"example": null,
"minimum": 0
},
"manuallyVerified": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"exclude": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"error": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"format": {
"type": [
"string",
"null"
],
"description": "The container format, such as `mp4` or `mp3`.",
"example": "MP4A"
},
"duration": {
"type": "number",
"format": "double",
"description": "The file's length in seconds.",
"example": 36000.0
},
"bitRate": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Bits per second, if known.",
"example": 128000,
"minimum": 0
},
"language": {
"type": [
"string",
"null"
],
"description": "The file's language, if known.",
"example": "en-us"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"timeBase": {
"type": [
"string",
"null"
],
"description": "The time base, if known.",
"example": "1/44100"
},
"channels": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Audio channels, if known.",
"example": 2,
"minimum": 0
},
"channelLayout": {
"type": [
"string",
"null"
],
"description": "The channel layout, if known.",
"example": "stereo"
},
"chapters": {
"type": "array",
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "Chapters embedded in the file: none are read."
},
"embeddedCoverArt": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"metaTags": {
"type": "object",
"description": "Tags read from the file: none until the stored media probe reads\nthem."
},
"mimeType": {
"type": "string",
"description": "The file's media type, such as `audio/mp4`.",
"example": "audio/mp4"
}
}
},
"description": "The audio files, when fetched expanded."
},
"chapters": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "The chapters, when fetched expanded."
},
"tracks": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A track with its place in the book.",
"required": [
"index",
"startOffset",
"duration",
"title",
"contentUrl",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The track's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"startOffset": {
"type": "number",
"format": "double",
"description": "Where the track starts in the book, in seconds.",
"example": 0.0
},
"duration": {
"type": "number",
"format": "double",
"description": "The track's length in seconds.",
"example": 36000.0
},
"title": {
"type": "string",
"description": "The track's title: its file name.",
"example": "The First"
},
"contentUrl": {
"type": "string",
"description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
"example": "/player/api/items/li_8f14e45fceea467f/file/0"
},
"mimeType": {
"type": "string",
"description": "The track's media type.",
"example": "audio/mp4"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"metadata": {
"oneOf": [
{
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "The tracks with their place in the book, when fetched expanded."
}
}
},
"numFiles": {
"type": "integer",
"format": "int64",
"description": "Files in the item.",
"example": 1,
"minimum": 0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in all its files.",
"example": 100000,
"minimum": 0
},
"libraryFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A file of an item, in the expanded item's `libraryFiles`.",
"required": [
"ino",
"metadata",
"addedAt",
"updatedAt",
"fileType"
],
"properties": {
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"fileType": {
"type": "string",
"description": "Always `audio`.",
"example": "audio"
}
}
},
"description": "The item's files, when the item is fetched expanded."
},
"userMediaProgress": {
"oneOf": [
{
"type": "object",
"description": "The patron's progress, when the app asked for it.",
"required": [
"id",
"userId",
"libraryItemId",
"mediaItemId",
"mediaItemType",
"duration",
"progress",
"currentTime",
"isFinished",
"hideFromContinueListening",
"lastUpdate",
"startedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The progress id: the item id (one record per patron and item).",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaItemId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"mediaItemType": {
"type": "string",
"description": "Always `book`.",
"example": "book"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds, as last reported.",
"example": 36000.0
},
"progress": {
"type": "number",
"format": "double",
"description": "The share listened, from 0 to 1.",
"example": 0.05
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished it.",
"example": false
},
"hideFromContinueListening": {
"type": "boolean",
"description": "Whether it is hidden from continue listening.",
"example": false
},
"ebookLocation": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"ebookProgress": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Always null.",
"example": null
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When the progress last changed, in epoch milliseconds.",
"example": 1763630000000
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the patron started, in epoch milliseconds.",
"example": 1763620000000
},
"finishedAt": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron finished, in epoch milliseconds.",
"example": null
}
}
},
{
"type": "null"
}
]
},
"seriesSequence": {
"type": [
"string",
"null"
],
"description": "The item's place in a series, on a series' book list.",
"example": "1"
}
}
},
"description": "The items, in series order."
}
}
},
"description": "The author's series with their items, when asked for."
}
}
},
"description": "Matching authors."
}
}
}
Status 400: A query value is out of range, or the terms do not parse.
Bad Request
Schema:
A text/plain body: a string.
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 404: No such library.
Not Found
Schema:
A text/plain body: a string.
Status 500: The library could not be read.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: The search index is being built; retry.
Service Unavailable
Schema:
A text/plain body: a string.
Adds up the library's items and their runtimes.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
idpathstringrequiredLibrary id.
-
200Totals over the items the patron may see (runtimes over the first 20000). Body:
LibraryStats(application/json)6 fieldstotalItemsinteger (int64)requiredItems. At least 0.totalAuthorsinteger (int64)requiredAuthors. At least 0.totalGenresinteger (int64)requiredGenres. At least 0.totalDurationnumber (double)requiredSeconds of audio in all.numAudioTracksinteger (int64)requiredAudio tracks in all. At least 0.totalSizeinteger (int64)requiredBytes in all: not counted. At least 0.
- 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 404No such library. Body: string (
text/plain) - 500The library could not be read. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/libraries/<id>/stats' \
-H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/libraries/<id>/stats' `
-Headers @{ Authorization = 'Bearer <playerToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/player/api/libraries/<id>/stats",
headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/libraries/<id>/stats", {
headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/player/api/libraries/<id>/stats")
.header("Authorization", "Bearer <playerToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: Totals over the items the patron may see (runtimes over the first 20000).
{
"totalItems": 1,
"totalAuthors": 1,
"totalGenres": 1,
"totalDuration": 36000.0,
"numAudioTracks": 1,
"totalSize": 100000
}
Schema:
{
"type": "object",
"description": "`GET /api/libraries/{id}/stats`.",
"required": [
"totalItems",
"totalAuthors",
"totalGenres",
"totalDuration",
"numAudioTracks",
"totalSize"
],
"properties": {
"totalItems": {
"type": "integer",
"format": "int64",
"description": "Items.",
"example": 1,
"minimum": 0
},
"totalAuthors": {
"type": "integer",
"format": "int64",
"description": "Authors.",
"example": 1,
"minimum": 0
},
"totalGenres": {
"type": "integer",
"format": "int64",
"description": "Genres.",
"example": 1,
"minimum": 0
},
"totalDuration": {
"type": "number",
"format": "double",
"description": "Seconds of audio in all.",
"example": 36000.0
},
"numAudioTracks": {
"type": "integer",
"format": "int64",
"description": "Audio tracks in all.",
"example": 1,
"minimum": 0
},
"totalSize": {
"type": "integer",
"format": "int64",
"description": "Bytes in all: not counted.",
"example": 100000,
"minimum": 0
}
}
}
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 404: No such library.
Not Found
Schema:
A text/plain body: a string.
Status 500: The library could not be read.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Reads the library's filter values.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
idpathstringrequiredLibrary id.
-
200The filter values. Body:
FilterData(application/json)14 fieldsauthorsarray ofNamedRefrequiredAuthors with at least one item.genresarray of stringrequiredGenres.tagsarray of stringrequiredTags: none are shown.seriesarray ofNamedRefrequiredSeries with at least one item.narratorsarray of stringrequiredNarrators.languagesarray of stringrequiredLanguages.publishersarray of stringrequiredPublishers.publishedDecadesarray of stringrequiredDecades of publication: none are offered.bookCountinteger (int64)requiredItems in the library. At least 0.authorCountinteger (int64)requiredAuthors in the library. At least 0.seriesCountinteger (int64)requiredSeries in the library. At least 0.podcastCountinteger (int64)requiredAlways 0. At least 0.numberEpisodesinteger (int64)requiredAlways 0. At least 0.loadedAtinteger (int64)requiredWhen the values were read, in epoch milliseconds.
- 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 404No such library. Body: string (
text/plain) - 500The library could not be read. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/libraries/<id>/filterdata' \
-H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/libraries/<id>/filterdata' `
-Headers @{ Authorization = 'Bearer <playerToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/player/api/libraries/<id>/filterdata",
headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/libraries/<id>/filterdata", {
headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/player/api/libraries/<id>/filterdata")
.header("Authorization", "Bearer <playerToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The filter values.
{
"authors": [
{
"id": "li_8f14e45fceea467f",
"name": "Ann Author"
}
],
"genres": [
"Fantasy"
],
"tags": [],
"series": [
{
"id": "li_8f14e45fceea467f",
"name": "Ann Author"
}
],
"narrators": [
"Nia Narrator"
],
"languages": [
"en-us"
],
"publishers": [
"Example Press"
],
"publishedDecades": [
"2020"
],
"bookCount": 1,
"authorCount": 1,
"seriesCount": 1,
"podcastCount": 0,
"numberEpisodes": 0,
"loadedAt": 1763630000000
}
Schema:
{
"type": "object",
"description": "The values an app offers as filters.",
"required": [
"authors",
"genres",
"tags",
"series",
"narrators",
"languages",
"publishers",
"publishedDecades",
"bookCount",
"authorCount",
"seriesCount",
"podcastCount",
"numberEpisodes",
"loadedAt"
],
"properties": {
"authors": {
"type": "array",
"items": {
"type": "object",
"description": "An id and a name.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its display name.",
"example": "Ann Author"
}
}
},
"description": "Authors with at least one item."
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"description": "Genres.",
"example": [
"Fantasy"
]
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags: none are shown.",
"example": []
},
"series": {
"type": "array",
"items": {
"type": "object",
"description": "An id and a name.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its display name.",
"example": "Ann Author"
}
}
},
"description": "Series with at least one item."
},
"narrators": {
"type": "array",
"items": {
"type": "string"
},
"description": "Narrators.",
"example": [
"Nia Narrator"
]
},
"languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Languages.",
"example": [
"en-us"
]
},
"publishers": {
"type": "array",
"items": {
"type": "string"
},
"description": "Publishers.",
"example": [
"Example Press"
]
},
"publishedDecades": {
"type": "array",
"items": {
"type": "string"
},
"description": "Decades of publication: none are offered.",
"example": [
"2020"
]
},
"bookCount": {
"type": "integer",
"format": "int64",
"description": "Items in the library.",
"example": 1,
"minimum": 0
},
"authorCount": {
"type": "integer",
"format": "int64",
"description": "Authors in the library.",
"example": 1,
"minimum": 0
},
"seriesCount": {
"type": "integer",
"format": "int64",
"description": "Series in the library.",
"example": 1,
"minimum": 0
},
"podcastCount": {
"type": "integer",
"format": "int64",
"description": "Always 0.",
"example": 0,
"minimum": 0
},
"numberEpisodes": {
"type": "integer",
"format": "int64",
"description": "Always 0.",
"example": 0,
"minimum": 0
},
"loadedAt": {
"type": "integer",
"format": "int64",
"description": "When the values were read, in epoch milliseconds.",
"example": 1763630000000
}
}
}
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 404: No such library.
Not Found
Schema:
A text/plain body: a string.
Status 500: The library could not be read.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Reads one series with its items and the patron's progress through it.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
idpathstringrequiredSeries id.
-
200The series. Body:
Series(application/json)9 fieldsidstringrequiredThe series id.namestringrequiredIts name.nameIgnorePrefixstringrequiredThe name for sorting.descriptionstring or nullIts description: none.addedAtinteger (int64)requiredWhen the library first saw it, in epoch milliseconds.updatedAtinteger (int64)requiredWhen it last changed, in epoch milliseconds.libraryIdstringrequiredThe library it is listed in.booksarray ofLibraryItemor nullIts items in series order, on lists.progressSeriesProgressor nullThe patron's progress through it, when asked for.
- 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 404No such series the patron may see. Body: string (
text/plain) - 500The library could not be read. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/series/<id>' \
-H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/series/<id>' `
-Headers @{ Authorization = 'Bearer <playerToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/player/api/series/<id>",
headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/series/<id>", {
headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/player/api/series/<id>")
.header("Authorization", "Bearer <playerToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The series.
{
"id": "li_8f14e45fceea467f",
"name": "Ann Author",
"nameIgnorePrefix": "Saga, The",
"description": "A short description.",
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"libraryId": "bookclerk-library",
"books": [
{
"id": "li_8f14e45fceea467f",
"ino": "0",
"oldLibraryItemId": null,
"libraryId": "bookclerk-library",
"folderId": "bookclerk-library",
"path": "/the-first.m4b",
"relPath": "the-first.m4b",
"isFile": true,
"mtimeMs": 1763600000000,
"ctimeMs": 1763600000000,
"birthtimeMs": 1763600000000,
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"isMissing": false,
"isInvalid": false,
"mediaType": "book",
"media": {
"id": "li_8f14e45fceea467f",
"libraryItemId": "li_8f14e45fceea467f",
"metadata": {
"title": "The First",
"titleIgnorePrefix": "First, The",
"authors": [],
"authorName": "Ann Author",
"authorNameLF": "Author, Ann",
"narrators": [
"Nia Narrator"
],
"narratorName": "Nia Narrator",
"series": [],
"seriesName": "The Saga #1",
"genres": [
"Fantasy"
],
"explicit": false,
"abridged": false
},
"coverPath": "/player/api/items/li_8f14e45fceea467f/cover",
"tags": [],
"numTracks": 1,
"numAudioFiles": 1,
"numChapters": 0,
"duration": 36000.0,
"size": 100000,
"audioFiles": [],
"chapters": [],
"tracks": []
},
"numFiles": 1,
"size": 100000,
"libraryFiles": [
{
"ino": "0",
"metadata": {
"filename": "the-first.m4b",
"ext": ".m4b",
"path": "/the-first.m4b",
"relPath": "the-first.m4b",
"size": 100000,
"mtimeMs": 1763600000000,
"ctimeMs": 1763600000000,
"birthtimeMs": 1763600000000
},
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"fileType": "audio"
}
],
"userMediaProgress": {
"id": "li_8f14e45fceea467f",
"userId": "42",
"libraryItemId": "li_8f14e45fceea467f",
"episodeId": null,
"mediaItemId": "li_8f14e45fceea467f",
"mediaItemType": "book",
"duration": 36000.0,
"progress": 0.05,
"currentTime": 1830.5,
"isFinished": false,
"hideFromContinueListening": false,
"ebookLocation": null,
"ebookProgress": null,
"lastUpdate": 1763630000000,
"startedAt": 1763620000000,
"finishedAt": null
},
"seriesSequence": "1"
}
],
"progress": {
"libraryItemIds": [
"li_8f14e45fceea467f"
],
"libraryItemIdsFinished": [],
"isFinished": false
}
}
Schema:
{
"type": "object",
"description": "A series.",
"required": [
"id",
"name",
"nameIgnorePrefix",
"addedAt",
"updatedAt",
"libraryId"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its name.",
"example": "Ann Author"
},
"nameIgnorePrefix": {
"type": "string",
"description": "The name for sorting.",
"example": "Saga, The"
},
"description": {
"type": [
"string",
"null"
],
"description": "Its description: none.",
"example": "A short description."
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the library first saw it, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When it last changed, in epoch milliseconds.",
"example": 1763630000000
},
"libraryId": {
"type": "string",
"description": "The library it is listed in.",
"example": "bookclerk-library"
},
"books": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "An item: an edition with a stored copy.",
"required": [
"id",
"ino",
"libraryId",
"folderId",
"path",
"relPath",
"isFile",
"mtimeMs",
"ctimeMs",
"birthtimeMs",
"addedAt",
"updatedAt",
"isMissing",
"isInvalid",
"mediaType",
"media",
"numFiles",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The item id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"ino": {
"type": "string",
"description": "The item's inode as apps expect one: the edition id again.",
"example": "0"
},
"oldLibraryItemId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"libraryId": {
"type": "string",
"description": "The library the item is listed in.",
"example": "bookclerk-library"
},
"folderId": {
"type": "string",
"description": "The folder id: the library id.",
"example": "bookclerk-library"
},
"path": {
"type": "string",
"description": "A display path: the title.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the title.",
"example": "the-first.m4b"
},
"isFile": {
"type": "boolean",
"description": "Always false: an item is a folder of tracks.",
"example": true
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy last changed, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the item joined the library, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When its record last changed, in epoch milliseconds.",
"example": 1763630000000
},
"isMissing": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"isInvalid": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"mediaType": {
"type": "string",
"description": "Always [`MEDIA_TYPE_BOOK`].",
"example": "book"
},
"media": {
"type": "object",
"description": "The book.",
"required": [
"id",
"metadata",
"tags",
"numTracks",
"numAudioFiles",
"numChapters",
"duration",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The media id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"libraryItemId": {
"type": [
"string",
"null"
],
"description": "The item id, when fetched expanded.",
"example": "li_8f14e45fceea467f"
},
"metadata": {
"type": "object",
"description": "The book's metadata.",
"required": [
"title",
"titleIgnorePrefix",
"authors",
"authorName",
"authorNameLF",
"narrators",
"narratorName",
"series",
"seriesName",
"genres",
"explicit",
"abridged"
],
"properties": {
"title": {
"type": "string",
"description": "The title.",
"example": "The First"
},
"titleIgnorePrefix": {
"type": "string",
"description": "The title for sorting.",
"example": "First, The"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "The subtitle, if any.",
"example": "A Novel"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"description": "An id and a name.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its display name.",
"example": "Ann Author"
}
}
},
"description": "The authors."
},
"authorName": {
"type": "string",
"description": "The authors' names joined with `, `.",
"example": "Ann Author"
},
"authorNameLF": {
"type": "string",
"description": "The authors' names, family name first, joined with `, `.",
"example": "Author, Ann"
},
"narrators": {
"type": "array",
"items": {
"type": "string"
},
"description": "The narrators' names.",
"example": [
"Nia Narrator"
]
},
"narratorName": {
"type": "string",
"description": "The narrators' names joined with `, `.",
"example": "Nia Narrator"
},
"series": {
"type": "array",
"items": {
"type": "object",
"description": "A series an item belongs to, with the item's place in it.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The series name.",
"example": "Ann Author"
},
"sequence": {
"type": [
"string",
"null"
],
"description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
"example": "1"
}
}
},
"description": "The series the book is in."
},
"seriesName": {
"type": "string",
"description": "The series names with the book's place (`Name #2`), joined.",
"example": "The Saga #1"
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"description": "Genres.",
"example": [
"Fantasy"
]
},
"publishedYear": {
"type": [
"string",
"null"
],
"description": "The year of publication, as a string (`\"2019\"`).",
"example": "2024"
},
"publishedDate": {
"type": [
"string",
"null"
],
"description": "The date of publication, if known.",
"example": "2024-03-01"
},
"publisher": {
"type": [
"string",
"null"
],
"description": "The publisher.",
"example": "Example Press"
},
"description": {
"type": [
"string",
"null"
],
"description": "The description, as the library stores it.",
"example": "A short description."
},
"descriptionPlain": {
"type": [
"string",
"null"
],
"description": "The description with markup removed.",
"example": "A short description."
},
"isbn": {
"type": [
"string",
"null"
],
"description": "The ISBN, if known.",
"example": "9780000000002"
},
"asin": {
"type": [
"string",
"null"
],
"description": "The ASIN, if known.",
"example": "B000000000"
},
"language": {
"type": [
"string",
"null"
],
"description": "The language.",
"example": "en-us"
},
"explicit": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"abridged": {
"type": "boolean",
"description": "Whether the edition is abridged.",
"example": false
}
}
},
"coverPath": {
"type": [
"string",
"null"
],
"description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
"example": "/player/api/items/li_8f14e45fceea467f/cover"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags: none.",
"example": []
},
"numTracks": {
"type": "integer",
"format": "int64",
"description": "Tracks in play order.",
"example": 1,
"minimum": 0
},
"numAudioFiles": {
"type": "integer",
"format": "int64",
"description": "Audio files.",
"example": 1,
"minimum": 0
},
"numChapters": {
"type": "integer",
"format": "int64",
"description": "Chapters.",
"example": 0,
"minimum": 0
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds.",
"example": 36000.0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in its audio files.",
"example": 100000,
"minimum": 0
},
"audioFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "An audio file of a book.",
"required": [
"index",
"ino",
"metadata",
"addedAt",
"updatedAt",
"manuallyVerified",
"exclude",
"duration",
"chapters",
"metaTags",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The file's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"trackNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number the file's tags state: not read.",
"example": 1,
"minimum": 0
},
"discNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number the file's tags state: not read.",
"example": null,
"minimum": 0
},
"trackNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number in the file name: not read.",
"example": null,
"minimum": 0
},
"discNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number in the file name: not read.",
"example": null,
"minimum": 0
},
"manuallyVerified": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"exclude": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"error": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"format": {
"type": [
"string",
"null"
],
"description": "The container format, such as `mp4` or `mp3`.",
"example": "MP4A"
},
"duration": {
"type": "number",
"format": "double",
"description": "The file's length in seconds.",
"example": 36000.0
},
"bitRate": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Bits per second, if known.",
"example": 128000,
"minimum": 0
},
"language": {
"type": [
"string",
"null"
],
"description": "The file's language, if known.",
"example": "en-us"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"timeBase": {
"type": [
"string",
"null"
],
"description": "The time base, if known.",
"example": "1/44100"
},
"channels": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Audio channels, if known.",
"example": 2,
"minimum": 0
},
"channelLayout": {
"type": [
"string",
"null"
],
"description": "The channel layout, if known.",
"example": "stereo"
},
"chapters": {
"type": "array",
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "Chapters embedded in the file: none are read."
},
"embeddedCoverArt": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"metaTags": {
"type": "object",
"description": "Tags read from the file: none until the stored media probe reads\nthem."
},
"mimeType": {
"type": "string",
"description": "The file's media type, such as `audio/mp4`.",
"example": "audio/mp4"
}
}
},
"description": "The audio files, when fetched expanded."
},
"chapters": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "The chapters, when fetched expanded."
},
"tracks": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A track with its place in the book.",
"required": [
"index",
"startOffset",
"duration",
"title",
"contentUrl",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The track's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"startOffset": {
"type": "number",
"format": "double",
"description": "Where the track starts in the book, in seconds.",
"example": 0.0
},
"duration": {
"type": "number",
"format": "double",
"description": "The track's length in seconds.",
"example": 36000.0
},
"title": {
"type": "string",
"description": "The track's title: its file name.",
"example": "The First"
},
"contentUrl": {
"type": "string",
"description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
"example": "/player/api/items/li_8f14e45fceea467f/file/0"
},
"mimeType": {
"type": "string",
"description": "The track's media type.",
"example": "audio/mp4"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"metadata": {
"oneOf": [
{
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "The tracks with their place in the book, when fetched expanded."
}
}
},
"numFiles": {
"type": "integer",
"format": "int64",
"description": "Files in the item.",
"example": 1,
"minimum": 0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in all its files.",
"example": 100000,
"minimum": 0
},
"libraryFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A file of an item, in the expanded item's `libraryFiles`.",
"required": [
"ino",
"metadata",
"addedAt",
"updatedAt",
"fileType"
],
"properties": {
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"fileType": {
"type": "string",
"description": "Always `audio`.",
"example": "audio"
}
}
},
"description": "The item's files, when the item is fetched expanded."
},
"userMediaProgress": {
"oneOf": [
{
"type": "object",
"description": "The patron's progress, when the app asked for it.",
"required": [
"id",
"userId",
"libraryItemId",
"mediaItemId",
"mediaItemType",
"duration",
"progress",
"currentTime",
"isFinished",
"hideFromContinueListening",
"lastUpdate",
"startedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The progress id: the item id (one record per patron and item).",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaItemId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"mediaItemType": {
"type": "string",
"description": "Always `book`.",
"example": "book"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds, as last reported.",
"example": 36000.0
},
"progress": {
"type": "number",
"format": "double",
"description": "The share listened, from 0 to 1.",
"example": 0.05
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished it.",
"example": false
},
"hideFromContinueListening": {
"type": "boolean",
"description": "Whether it is hidden from continue listening.",
"example": false
},
"ebookLocation": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"ebookProgress": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Always null.",
"example": null
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When the progress last changed, in epoch milliseconds.",
"example": 1763630000000
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the patron started, in epoch milliseconds.",
"example": 1763620000000
},
"finishedAt": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron finished, in epoch milliseconds.",
"example": null
}
}
},
{
"type": "null"
}
]
},
"seriesSequence": {
"type": [
"string",
"null"
],
"description": "The item's place in a series, on a series' book list.",
"example": "1"
}
}
},
"description": "Its items in series order, on lists."
},
"progress": {
"oneOf": [
{
"type": "object",
"description": "The patron's progress through it, when asked for.",
"required": [
"libraryItemIds",
"libraryItemIdsFinished",
"isFinished"
],
"properties": {
"libraryItemIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "The series' items, by id.",
"example": [
"li_8f14e45fceea467f"
]
},
"libraryItemIdsFinished": {
"type": "array",
"items": {
"type": "string"
},
"description": "Those the patron finished.",
"example": []
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished every one.",
"example": false
}
}
},
{
"type": "null"
}
]
}
}
}
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 404: No such series the patron may see.
Not Found
Schema:
A text/plain body: a string.
Status 500: The library could not be read.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Reads one author, with their items and series when asked for.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
idpathstringrequiredAuthor id.includequerystringitemsand/orseries.
-
200The author. Body:
Author(application/json)12 fieldsidstringrequiredThe contributor id.asinstring or nullAlways null.namestringrequiredThe author's name.lastFirststringrequiredThe name family name first.descriptionstring or nullAlways null.imagePathstring or nullAlways null: no author images.libraryIdstringrequiredThe library it is listed in.addedAtinteger (int64)requiredWhen the library first saw the author, in epoch milliseconds.updatedAtinteger (int64)requiredWhen the record last changed, in epoch milliseconds.numBooksinteger (int64)requiredItems by the author the patron can see. At least 0.libraryItemsarray ofLibraryItemor nullThe author's items, when asked for.seriesarray ofAuthorSeriesor nullThe author's series with their items, when asked for.
- 400A query value is out of range. Body: string (
text/plain) - 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 404No such author the patron may see. Body: string (
text/plain) - 500The library could not be read. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/authors/<id>' \
-H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/authors/<id>' `
-Headers @{ Authorization = 'Bearer <playerToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/player/api/authors/<id>",
headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/authors/<id>", {
headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/player/api/authors/<id>")
.header("Authorization", "Bearer <playerToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The author.
{
"id": "li_8f14e45fceea467f",
"asin": "B000000000",
"name": "Ann Author",
"lastFirst": "Author, Ann",
"description": "A short description.",
"imagePath": null,
"libraryId": "bookclerk-library",
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"numBooks": 1,
"libraryItems": [
{
"id": "li_8f14e45fceea467f",
"ino": "0",
"oldLibraryItemId": null,
"libraryId": "bookclerk-library",
"folderId": "bookclerk-library",
"path": "/the-first.m4b",
"relPath": "the-first.m4b",
"isFile": true,
"mtimeMs": 1763600000000,
"ctimeMs": 1763600000000,
"birthtimeMs": 1763600000000,
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"isMissing": false,
"isInvalid": false,
"mediaType": "book",
"media": {
"id": "li_8f14e45fceea467f",
"libraryItemId": "li_8f14e45fceea467f",
"metadata": {
"title": "The First",
"titleIgnorePrefix": "First, The",
"authors": [],
"authorName": "Ann Author",
"authorNameLF": "Author, Ann",
"narrators": [
"Nia Narrator"
],
"narratorName": "Nia Narrator",
"series": [],
"seriesName": "The Saga #1",
"genres": [
"Fantasy"
],
"explicit": false,
"abridged": false
},
"coverPath": "/player/api/items/li_8f14e45fceea467f/cover",
"tags": [],
"numTracks": 1,
"numAudioFiles": 1,
"numChapters": 0,
"duration": 36000.0,
"size": 100000,
"audioFiles": [],
"chapters": [],
"tracks": []
},
"numFiles": 1,
"size": 100000,
"libraryFiles": [
{
"ino": "0",
"metadata": {
"filename": "the-first.m4b",
"ext": ".m4b",
"path": "/the-first.m4b",
"relPath": "the-first.m4b",
"size": 100000,
"mtimeMs": 1763600000000,
"ctimeMs": 1763600000000,
"birthtimeMs": 1763600000000
},
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"fileType": "audio"
}
],
"userMediaProgress": {
"id": "li_8f14e45fceea467f",
"userId": "42",
"libraryItemId": "li_8f14e45fceea467f",
"episodeId": null,
"mediaItemId": "li_8f14e45fceea467f",
"mediaItemType": "book",
"duration": 36000.0,
"progress": 0.05,
"currentTime": 1830.5,
"isFinished": false,
"hideFromContinueListening": false,
"ebookLocation": null,
"ebookProgress": null,
"lastUpdate": 1763630000000,
"startedAt": 1763620000000,
"finishedAt": null
},
"seriesSequence": "1"
}
],
"series": [
{
"id": "li_8f14e45fceea467f",
"name": "Ann Author",
"items": [
{
"id": "li_8f14e45fceea467f",
"ino": "0",
"libraryId": "bookclerk-library",
"folderId": "bookclerk-library",
"path": "/the-first.m4b",
"relPath": "the-first.m4b",
"isFile": true,
"mtimeMs": 1763600000000,
"ctimeMs": 1763600000000,
"birthtimeMs": 1763600000000,
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"isMissing": false,
"isInvalid": false,
"mediaType": "book",
"media": {
"id": "li_8f14e45fceea467f",
"metadata": {
"title": "The First",
"titleIgnorePrefix": "First, The",
"authors": [],
"authorName": "Ann Author",
"authorNameLF": "Author, Ann",
"narrators": [
"Nia Narrator"
],
"narratorName": "Nia Narrator",
"series": [],
"seriesName": "The Saga #1",
"genres": [
"Fantasy"
],
"explicit": false,
"abridged": false
},
"tags": [],
"numTracks": 1,
"numAudioFiles": 1,
"numChapters": 0,
"duration": 36000.0,
"size": 100000
},
"numFiles": 1,
"size": 100000
}
]
}
]
}
Schema:
{
"type": "object",
"description": "An author.",
"required": [
"id",
"name",
"lastFirst",
"libraryId",
"addedAt",
"updatedAt",
"numBooks"
],
"properties": {
"id": {
"type": "string",
"description": "The contributor id.",
"example": "li_8f14e45fceea467f"
},
"asin": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": "B000000000"
},
"name": {
"type": "string",
"description": "The author's name.",
"example": "Ann Author"
},
"lastFirst": {
"type": "string",
"description": "The name family name first.",
"example": "Author, Ann"
},
"description": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": "A short description."
},
"imagePath": {
"type": [
"string",
"null"
],
"description": "Always null: no author images.",
"example": null
},
"libraryId": {
"type": "string",
"description": "The library it is listed in.",
"example": "bookclerk-library"
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the library first saw the author, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the record last changed, in epoch milliseconds.",
"example": 1763630000000
},
"numBooks": {
"type": "integer",
"format": "int64",
"description": "Items by the author the patron can see.",
"example": 1,
"minimum": 0
},
"libraryItems": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "An item: an edition with a stored copy.",
"required": [
"id",
"ino",
"libraryId",
"folderId",
"path",
"relPath",
"isFile",
"mtimeMs",
"ctimeMs",
"birthtimeMs",
"addedAt",
"updatedAt",
"isMissing",
"isInvalid",
"mediaType",
"media",
"numFiles",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The item id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"ino": {
"type": "string",
"description": "The item's inode as apps expect one: the edition id again.",
"example": "0"
},
"oldLibraryItemId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"libraryId": {
"type": "string",
"description": "The library the item is listed in.",
"example": "bookclerk-library"
},
"folderId": {
"type": "string",
"description": "The folder id: the library id.",
"example": "bookclerk-library"
},
"path": {
"type": "string",
"description": "A display path: the title.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the title.",
"example": "the-first.m4b"
},
"isFile": {
"type": "boolean",
"description": "Always false: an item is a folder of tracks.",
"example": true
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy last changed, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the item joined the library, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When its record last changed, in epoch milliseconds.",
"example": 1763630000000
},
"isMissing": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"isInvalid": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"mediaType": {
"type": "string",
"description": "Always [`MEDIA_TYPE_BOOK`].",
"example": "book"
},
"media": {
"type": "object",
"description": "The book.",
"required": [
"id",
"metadata",
"tags",
"numTracks",
"numAudioFiles",
"numChapters",
"duration",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The media id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"libraryItemId": {
"type": [
"string",
"null"
],
"description": "The item id, when fetched expanded.",
"example": "li_8f14e45fceea467f"
},
"metadata": {
"type": "object",
"description": "The book's metadata.",
"required": [
"title",
"titleIgnorePrefix",
"authors",
"authorName",
"authorNameLF",
"narrators",
"narratorName",
"series",
"seriesName",
"genres",
"explicit",
"abridged"
],
"properties": {
"title": {
"type": "string",
"description": "The title.",
"example": "The First"
},
"titleIgnorePrefix": {
"type": "string",
"description": "The title for sorting.",
"example": "First, The"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "The subtitle, if any.",
"example": "A Novel"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"description": "An id and a name.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its display name.",
"example": "Ann Author"
}
}
},
"description": "The authors."
},
"authorName": {
"type": "string",
"description": "The authors' names joined with `, `.",
"example": "Ann Author"
},
"authorNameLF": {
"type": "string",
"description": "The authors' names, family name first, joined with `, `.",
"example": "Author, Ann"
},
"narrators": {
"type": "array",
"items": {
"type": "string"
},
"description": "The narrators' names.",
"example": [
"Nia Narrator"
]
},
"narratorName": {
"type": "string",
"description": "The narrators' names joined with `, `.",
"example": "Nia Narrator"
},
"series": {
"type": "array",
"items": {
"type": "object",
"description": "A series an item belongs to, with the item's place in it.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The series name.",
"example": "Ann Author"
},
"sequence": {
"type": [
"string",
"null"
],
"description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
"example": "1"
}
}
},
"description": "The series the book is in."
},
"seriesName": {
"type": "string",
"description": "The series names with the book's place (`Name #2`), joined.",
"example": "The Saga #1"
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"description": "Genres.",
"example": [
"Fantasy"
]
},
"publishedYear": {
"type": [
"string",
"null"
],
"description": "The year of publication, as a string (`\"2019\"`).",
"example": "2024"
},
"publishedDate": {
"type": [
"string",
"null"
],
"description": "The date of publication, if known.",
"example": "2024-03-01"
},
"publisher": {
"type": [
"string",
"null"
],
"description": "The publisher.",
"example": "Example Press"
},
"description": {
"type": [
"string",
"null"
],
"description": "The description, as the library stores it.",
"example": "A short description."
},
"descriptionPlain": {
"type": [
"string",
"null"
],
"description": "The description with markup removed.",
"example": "A short description."
},
"isbn": {
"type": [
"string",
"null"
],
"description": "The ISBN, if known.",
"example": "9780000000002"
},
"asin": {
"type": [
"string",
"null"
],
"description": "The ASIN, if known.",
"example": "B000000000"
},
"language": {
"type": [
"string",
"null"
],
"description": "The language.",
"example": "en-us"
},
"explicit": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"abridged": {
"type": "boolean",
"description": "Whether the edition is abridged.",
"example": false
}
}
},
"coverPath": {
"type": [
"string",
"null"
],
"description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
"example": "/player/api/items/li_8f14e45fceea467f/cover"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags: none.",
"example": []
},
"numTracks": {
"type": "integer",
"format": "int64",
"description": "Tracks in play order.",
"example": 1,
"minimum": 0
},
"numAudioFiles": {
"type": "integer",
"format": "int64",
"description": "Audio files.",
"example": 1,
"minimum": 0
},
"numChapters": {
"type": "integer",
"format": "int64",
"description": "Chapters.",
"example": 0,
"minimum": 0
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds.",
"example": 36000.0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in its audio files.",
"example": 100000,
"minimum": 0
},
"audioFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "An audio file of a book.",
"required": [
"index",
"ino",
"metadata",
"addedAt",
"updatedAt",
"manuallyVerified",
"exclude",
"duration",
"chapters",
"metaTags",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The file's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"trackNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number the file's tags state: not read.",
"example": 1,
"minimum": 0
},
"discNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number the file's tags state: not read.",
"example": null,
"minimum": 0
},
"trackNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number in the file name: not read.",
"example": null,
"minimum": 0
},
"discNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number in the file name: not read.",
"example": null,
"minimum": 0
},
"manuallyVerified": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"exclude": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"error": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"format": {
"type": [
"string",
"null"
],
"description": "The container format, such as `mp4` or `mp3`.",
"example": "MP4A"
},
"duration": {
"type": "number",
"format": "double",
"description": "The file's length in seconds.",
"example": 36000.0
},
"bitRate": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Bits per second, if known.",
"example": 128000,
"minimum": 0
},
"language": {
"type": [
"string",
"null"
],
"description": "The file's language, if known.",
"example": "en-us"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"timeBase": {
"type": [
"string",
"null"
],
"description": "The time base, if known.",
"example": "1/44100"
},
"channels": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Audio channels, if known.",
"example": 2,
"minimum": 0
},
"channelLayout": {
"type": [
"string",
"null"
],
"description": "The channel layout, if known.",
"example": "stereo"
},
"chapters": {
"type": "array",
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "Chapters embedded in the file: none are read."
},
"embeddedCoverArt": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"metaTags": {
"type": "object",
"description": "Tags read from the file: none until the stored media probe reads\nthem."
},
"mimeType": {
"type": "string",
"description": "The file's media type, such as `audio/mp4`.",
"example": "audio/mp4"
}
}
},
"description": "The audio files, when fetched expanded."
},
"chapters": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "The chapters, when fetched expanded."
},
"tracks": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A track with its place in the book.",
"required": [
"index",
"startOffset",
"duration",
"title",
"contentUrl",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The track's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"startOffset": {
"type": "number",
"format": "double",
"description": "Where the track starts in the book, in seconds.",
"example": 0.0
},
"duration": {
"type": "number",
"format": "double",
"description": "The track's length in seconds.",
"example": 36000.0
},
"title": {
"type": "string",
"description": "The track's title: its file name.",
"example": "The First"
},
"contentUrl": {
"type": "string",
"description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
"example": "/player/api/items/li_8f14e45fceea467f/file/0"
},
"mimeType": {
"type": "string",
"description": "The track's media type.",
"example": "audio/mp4"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"metadata": {
"oneOf": [
{
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "The tracks with their place in the book, when fetched expanded."
}
}
},
"numFiles": {
"type": "integer",
"format": "int64",
"description": "Files in the item.",
"example": 1,
"minimum": 0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in all its files.",
"example": 100000,
"minimum": 0
},
"libraryFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A file of an item, in the expanded item's `libraryFiles`.",
"required": [
"ino",
"metadata",
"addedAt",
"updatedAt",
"fileType"
],
"properties": {
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"fileType": {
"type": "string",
"description": "Always `audio`.",
"example": "audio"
}
}
},
"description": "The item's files, when the item is fetched expanded."
},
"userMediaProgress": {
"oneOf": [
{
"type": "object",
"description": "The patron's progress, when the app asked for it.",
"required": [
"id",
"userId",
"libraryItemId",
"mediaItemId",
"mediaItemType",
"duration",
"progress",
"currentTime",
"isFinished",
"hideFromContinueListening",
"lastUpdate",
"startedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The progress id: the item id (one record per patron and item).",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaItemId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"mediaItemType": {
"type": "string",
"description": "Always `book`.",
"example": "book"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds, as last reported.",
"example": 36000.0
},
"progress": {
"type": "number",
"format": "double",
"description": "The share listened, from 0 to 1.",
"example": 0.05
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished it.",
"example": false
},
"hideFromContinueListening": {
"type": "boolean",
"description": "Whether it is hidden from continue listening.",
"example": false
},
"ebookLocation": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"ebookProgress": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Always null.",
"example": null
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When the progress last changed, in epoch milliseconds.",
"example": 1763630000000
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the patron started, in epoch milliseconds.",
"example": 1763620000000
},
"finishedAt": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron finished, in epoch milliseconds.",
"example": null
}
}
},
{
"type": "null"
}
]
},
"seriesSequence": {
"type": [
"string",
"null"
],
"description": "The item's place in a series, on a series' book list.",
"example": "1"
}
}
},
"description": "The author's items, when asked for."
},
"series": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A series of an author's, with the author's items in it.",
"required": [
"id",
"name",
"items"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The series name.",
"example": "Ann Author"
},
"items": {
"type": "array",
"items": {
"type": "object",
"description": "An item: an edition with a stored copy.",
"required": [
"id",
"ino",
"libraryId",
"folderId",
"path",
"relPath",
"isFile",
"mtimeMs",
"ctimeMs",
"birthtimeMs",
"addedAt",
"updatedAt",
"isMissing",
"isInvalid",
"mediaType",
"media",
"numFiles",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The item id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"ino": {
"type": "string",
"description": "The item's inode as apps expect one: the edition id again.",
"example": "0"
},
"oldLibraryItemId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"libraryId": {
"type": "string",
"description": "The library the item is listed in.",
"example": "bookclerk-library"
},
"folderId": {
"type": "string",
"description": "The folder id: the library id.",
"example": "bookclerk-library"
},
"path": {
"type": "string",
"description": "A display path: the title.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the title.",
"example": "the-first.m4b"
},
"isFile": {
"type": "boolean",
"description": "Always false: an item is a folder of tracks.",
"example": true
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy last changed, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the item joined the library, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When its record last changed, in epoch milliseconds.",
"example": 1763630000000
},
"isMissing": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"isInvalid": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"mediaType": {
"type": "string",
"description": "Always [`MEDIA_TYPE_BOOK`].",
"example": "book"
},
"media": {
"type": "object",
"description": "The book.",
"required": [
"id",
"metadata",
"tags",
"numTracks",
"numAudioFiles",
"numChapters",
"duration",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The media id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"libraryItemId": {
"type": [
"string",
"null"
],
"description": "The item id, when fetched expanded.",
"example": "li_8f14e45fceea467f"
},
"metadata": {
"type": "object",
"description": "The book's metadata.",
"required": [
"title",
"titleIgnorePrefix",
"authors",
"authorName",
"authorNameLF",
"narrators",
"narratorName",
"series",
"seriesName",
"genres",
"explicit",
"abridged"
],
"properties": {
"title": {
"type": "string",
"description": "The title.",
"example": "The First"
},
"titleIgnorePrefix": {
"type": "string",
"description": "The title for sorting.",
"example": "First, The"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "The subtitle, if any.",
"example": "A Novel"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"description": "An id and a name.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its display name.",
"example": "Ann Author"
}
}
},
"description": "The authors."
},
"authorName": {
"type": "string",
"description": "The authors' names joined with `, `.",
"example": "Ann Author"
},
"authorNameLF": {
"type": "string",
"description": "The authors' names, family name first, joined with `, `.",
"example": "Author, Ann"
},
"narrators": {
"type": "array",
"items": {
"type": "string"
},
"description": "The narrators' names.",
"example": [
"Nia Narrator"
]
},
"narratorName": {
"type": "string",
"description": "The narrators' names joined with `, `.",
"example": "Nia Narrator"
},
"series": {
"type": "array",
"items": {
"type": "object",
"description": "A series an item belongs to, with the item's place in it.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The series name.",
"example": "Ann Author"
},
"sequence": {
"type": [
"string",
"null"
],
"description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
"example": "1"
}
}
},
"description": "The series the book is in."
},
"seriesName": {
"type": "string",
"description": "The series names with the book's place (`Name #2`), joined.",
"example": "The Saga #1"
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"description": "Genres.",
"example": [
"Fantasy"
]
},
"publishedYear": {
"type": [
"string",
"null"
],
"description": "The year of publication, as a string (`\"2019\"`).",
"example": "2024"
},
"publishedDate": {
"type": [
"string",
"null"
],
"description": "The date of publication, if known.",
"example": "2024-03-01"
},
"publisher": {
"type": [
"string",
"null"
],
"description": "The publisher.",
"example": "Example Press"
},
"description": {
"type": [
"string",
"null"
],
"description": "The description, as the library stores it.",
"example": "A short description."
},
"descriptionPlain": {
"type": [
"string",
"null"
],
"description": "The description with markup removed.",
"example": "A short description."
},
"isbn": {
"type": [
"string",
"null"
],
"description": "The ISBN, if known.",
"example": "9780000000002"
},
"asin": {
"type": [
"string",
"null"
],
"description": "The ASIN, if known.",
"example": "B000000000"
},
"language": {
"type": [
"string",
"null"
],
"description": "The language.",
"example": "en-us"
},
"explicit": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"abridged": {
"type": "boolean",
"description": "Whether the edition is abridged.",
"example": false
}
}
},
"coverPath": {
"type": [
"string",
"null"
],
"description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
"example": "/player/api/items/li_8f14e45fceea467f/cover"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags: none.",
"example": []
},
"numTracks": {
"type": "integer",
"format": "int64",
"description": "Tracks in play order.",
"example": 1,
"minimum": 0
},
"numAudioFiles": {
"type": "integer",
"format": "int64",
"description": "Audio files.",
"example": 1,
"minimum": 0
},
"numChapters": {
"type": "integer",
"format": "int64",
"description": "Chapters.",
"example": 0,
"minimum": 0
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds.",
"example": 36000.0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in its audio files.",
"example": 100000,
"minimum": 0
},
"audioFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "An audio file of a book.",
"required": [
"index",
"ino",
"metadata",
"addedAt",
"updatedAt",
"manuallyVerified",
"exclude",
"duration",
"chapters",
"metaTags",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The file's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"trackNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number the file's tags state: not read.",
"example": 1,
"minimum": 0
},
"discNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number the file's tags state: not read.",
"example": null,
"minimum": 0
},
"trackNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number in the file name: not read.",
"example": null,
"minimum": 0
},
"discNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number in the file name: not read.",
"example": null,
"minimum": 0
},
"manuallyVerified": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"exclude": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"error": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"format": {
"type": [
"string",
"null"
],
"description": "The container format, such as `mp4` or `mp3`.",
"example": "MP4A"
},
"duration": {
"type": "number",
"format": "double",
"description": "The file's length in seconds.",
"example": 36000.0
},
"bitRate": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Bits per second, if known.",
"example": 128000,
"minimum": 0
},
"language": {
"type": [
"string",
"null"
],
"description": "The file's language, if known.",
"example": "en-us"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"timeBase": {
"type": [
"string",
"null"
],
"description": "The time base, if known.",
"example": "1/44100"
},
"channels": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Audio channels, if known.",
"example": 2,
"minimum": 0
},
"channelLayout": {
"type": [
"string",
"null"
],
"description": "The channel layout, if known.",
"example": "stereo"
},
"chapters": {
"type": "array",
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "Chapters embedded in the file: none are read."
},
"embeddedCoverArt": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"metaTags": {
"type": "object",
"description": "Tags read from the file: none until the stored media probe reads\nthem."
},
"mimeType": {
"type": "string",
"description": "The file's media type, such as `audio/mp4`.",
"example": "audio/mp4"
}
}
},
"description": "The audio files, when fetched expanded."
},
"chapters": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "The chapters, when fetched expanded."
},
"tracks": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A track with its place in the book.",
"required": [
"index",
"startOffset",
"duration",
"title",
"contentUrl",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The track's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"startOffset": {
"type": "number",
"format": "double",
"description": "Where the track starts in the book, in seconds.",
"example": 0.0
},
"duration": {
"type": "number",
"format": "double",
"description": "The track's length in seconds.",
"example": 36000.0
},
"title": {
"type": "string",
"description": "The track's title: its file name.",
"example": "The First"
},
"contentUrl": {
"type": "string",
"description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
"example": "/player/api/items/li_8f14e45fceea467f/file/0"
},
"mimeType": {
"type": "string",
"description": "The track's media type.",
"example": "audio/mp4"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"metadata": {
"oneOf": [
{
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "The tracks with their place in the book, when fetched expanded."
}
}
},
"numFiles": {
"type": "integer",
"format": "int64",
"description": "Files in the item.",
"example": 1,
"minimum": 0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in all its files.",
"example": 100000,
"minimum": 0
},
"libraryFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A file of an item, in the expanded item's `libraryFiles`.",
"required": [
"ino",
"metadata",
"addedAt",
"updatedAt",
"fileType"
],
"properties": {
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"fileType": {
"type": "string",
"description": "Always `audio`.",
"example": "audio"
}
}
},
"description": "The item's files, when the item is fetched expanded."
},
"userMediaProgress": {
"oneOf": [
{
"type": "object",
"description": "The patron's progress, when the app asked for it.",
"required": [
"id",
"userId",
"libraryItemId",
"mediaItemId",
"mediaItemType",
"duration",
"progress",
"currentTime",
"isFinished",
"hideFromContinueListening",
"lastUpdate",
"startedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The progress id: the item id (one record per patron and item).",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaItemId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"mediaItemType": {
"type": "string",
"description": "Always `book`.",
"example": "book"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds, as last reported.",
"example": 36000.0
},
"progress": {
"type": "number",
"format": "double",
"description": "The share listened, from 0 to 1.",
"example": 0.05
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished it.",
"example": false
},
"hideFromContinueListening": {
"type": "boolean",
"description": "Whether it is hidden from continue listening.",
"example": false
},
"ebookLocation": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"ebookProgress": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Always null.",
"example": null
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When the progress last changed, in epoch milliseconds.",
"example": 1763630000000
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the patron started, in epoch milliseconds.",
"example": 1763620000000
},
"finishedAt": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron finished, in epoch milliseconds.",
"example": null
}
}
},
{
"type": "null"
}
]
},
"seriesSequence": {
"type": [
"string",
"null"
],
"description": "The item's place in a series, on a series' book list.",
"example": "1"
}
}
},
"description": "The items, in series order."
}
}
},
"description": "The author's series with their items, when asked for."
}
}
}
Status 400: A query value is out of range.
Bad Request
Schema:
A text/plain body: a string.
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 404: No such author the patron may see.
Not Found
Schema:
A text/plain body: a string.
Status 500: The library could not be read.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Reads one item; expanded, with its tracks and files.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
idpathstringrequiredItem id.expandedqueryinteger (int32)1 to add tracks and files.includequerystringprogressto add the patron's progress.
-
200The item. Body:
LibraryItem(application/json)22 fieldsidstringrequiredThe item id: the edition id.inostringrequiredThe item's inode as apps expect one: the edition id again.oldLibraryItemIdstring or nullAlways null.libraryIdstringrequiredThe library the item is listed in.folderIdstringrequiredThe folder id: the library id.pathstringrequiredA display path: the title.relPathstringrequiredA display path: the title.isFilebooleanrequiredAlways false: an item is a folder of tracks.mtimeMsinteger (int64)requiredWhen the copy last changed, in epoch milliseconds.ctimeMsinteger (int64)requiredWhen the copy was stored, in epoch milliseconds.birthtimeMsinteger (int64)requiredWhen the copy was stored, in epoch milliseconds.addedAtinteger (int64)requiredWhen the item joined the library, in epoch milliseconds.updatedAtinteger (int64)requiredWhen its record last changed, in epoch milliseconds.isMissingbooleanrequiredAlways false.isInvalidbooleanrequiredAlways false.mediaTypestringrequiredAlways [MEDIA_TYPE_BOOK].mediaBookMediarequiredThe book.numFilesinteger (int64)requiredFiles in the item. At least 0.sizeinteger (int64)requiredBytes in all its files. At least 0.libraryFilesarray ofLibraryFileor nullThe item's files, when the item is fetched expanded.userMediaProgressMediaProgressor nullThe patron's progress, when the app asked for it.seriesSequencestring or nullThe item's place in a series, on a series' book list.
- 400A query value is out of range. Body: string (
text/plain) - 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 404No such item the patron may see. Body: string (
text/plain) - 500The library could not be read. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/items/<id>' \
-H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/items/<id>' `
-Headers @{ Authorization = 'Bearer <playerToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/player/api/items/<id>",
headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/items/<id>", {
headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/player/api/items/<id>")
.header("Authorization", "Bearer <playerToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The item.
{
"id": "li_8f14e45fceea467f",
"ino": "0",
"oldLibraryItemId": null,
"libraryId": "bookclerk-library",
"folderId": "bookclerk-library",
"path": "/the-first.m4b",
"relPath": "the-first.m4b",
"isFile": true,
"mtimeMs": 1763600000000,
"ctimeMs": 1763600000000,
"birthtimeMs": 1763600000000,
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"isMissing": false,
"isInvalid": false,
"mediaType": "book",
"media": {
"id": "li_8f14e45fceea467f",
"libraryItemId": "li_8f14e45fceea467f",
"metadata": {
"title": "The First",
"titleIgnorePrefix": "First, The",
"subtitle": "A Novel",
"authors": [
{
"id": "li_8f14e45fceea467f",
"name": "Ann Author"
}
],
"authorName": "Ann Author",
"authorNameLF": "Author, Ann",
"narrators": [
"Nia Narrator"
],
"narratorName": "Nia Narrator",
"series": [
{
"id": "li_8f14e45fceea467f",
"name": "Ann Author"
}
],
"seriesName": "The Saga #1",
"genres": [
"Fantasy"
],
"publishedYear": "2024",
"publishedDate": "2024-03-01",
"publisher": "Example Press",
"description": "A short description.",
"descriptionPlain": "A short description.",
"isbn": "9780000000002",
"asin": "B000000000",
"language": "en-us",
"explicit": false,
"abridged": false
},
"coverPath": "/player/api/items/li_8f14e45fceea467f/cover",
"tags": [],
"numTracks": 1,
"numAudioFiles": 1,
"numChapters": 0,
"duration": 36000.0,
"size": 100000,
"audioFiles": [
{
"index": 1,
"ino": "0",
"metadata": {
"filename": "the-first.m4b",
"ext": ".m4b",
"path": "/the-first.m4b",
"relPath": "the-first.m4b",
"size": 100000,
"mtimeMs": 1763600000000,
"ctimeMs": 1763600000000,
"birthtimeMs": 1763600000000
},
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"trackNumFromMeta": 1,
"discNumFromMeta": null,
"trackNumFromFilename": null,
"discNumFromFilename": null,
"manuallyVerified": false,
"exclude": false,
"error": null,
"format": "MP4A",
"duration": 36000.0,
"bitRate": 128000,
"language": "en-us",
"codec": "aac",
"timeBase": "1/44100",
"channels": 2,
"channelLayout": "stereo",
"chapters": [],
"embeddedCoverArt": null,
"metaTags": {},
"mimeType": "audio/mp4"
}
],
"chapters": [
{
"id": 1,
"start": 0.0,
"end": 600.0,
"title": "The First"
}
],
"tracks": [
{
"index": 1,
"startOffset": 0.0,
"duration": 36000.0,
"title": "The First",
"contentUrl": "/player/api/items/li_8f14e45fceea467f/file/0",
"mimeType": "audio/mp4",
"codec": "aac",
"metadata": {
"filename": "the-first.m4b",
"ext": ".m4b",
"path": "/the-first.m4b",
"relPath": "the-first.m4b",
"size": 100000,
"mtimeMs": 1763600000000,
"ctimeMs": 1763600000000,
"birthtimeMs": 1763600000000
}
}
]
},
"numFiles": 1,
"size": 100000,
"libraryFiles": [
{
"ino": "0",
"metadata": {
"filename": "the-first.m4b",
"ext": ".m4b",
"path": "/the-first.m4b",
"relPath": "the-first.m4b",
"size": 100000,
"mtimeMs": 1763600000000,
"ctimeMs": 1763600000000,
"birthtimeMs": 1763600000000
},
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"fileType": "audio"
}
],
"userMediaProgress": {
"id": "li_8f14e45fceea467f",
"userId": "42",
"libraryItemId": "li_8f14e45fceea467f",
"episodeId": null,
"mediaItemId": "li_8f14e45fceea467f",
"mediaItemType": "book",
"duration": 36000.0,
"progress": 0.05,
"currentTime": 1830.5,
"isFinished": false,
"hideFromContinueListening": false,
"ebookLocation": null,
"ebookProgress": null,
"lastUpdate": 1763630000000,
"startedAt": 1763620000000,
"finishedAt": null
},
"seriesSequence": "1"
}
Schema:
{
"type": "object",
"description": "An item: an edition with a stored copy.",
"required": [
"id",
"ino",
"libraryId",
"folderId",
"path",
"relPath",
"isFile",
"mtimeMs",
"ctimeMs",
"birthtimeMs",
"addedAt",
"updatedAt",
"isMissing",
"isInvalid",
"mediaType",
"media",
"numFiles",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The item id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"ino": {
"type": "string",
"description": "The item's inode as apps expect one: the edition id again.",
"example": "0"
},
"oldLibraryItemId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"libraryId": {
"type": "string",
"description": "The library the item is listed in.",
"example": "bookclerk-library"
},
"folderId": {
"type": "string",
"description": "The folder id: the library id.",
"example": "bookclerk-library"
},
"path": {
"type": "string",
"description": "A display path: the title.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the title.",
"example": "the-first.m4b"
},
"isFile": {
"type": "boolean",
"description": "Always false: an item is a folder of tracks.",
"example": true
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy last changed, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the item joined the library, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When its record last changed, in epoch milliseconds.",
"example": 1763630000000
},
"isMissing": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"isInvalid": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"mediaType": {
"type": "string",
"description": "Always [`MEDIA_TYPE_BOOK`].",
"example": "book"
},
"media": {
"type": "object",
"description": "The book.",
"required": [
"id",
"metadata",
"tags",
"numTracks",
"numAudioFiles",
"numChapters",
"duration",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The media id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"libraryItemId": {
"type": [
"string",
"null"
],
"description": "The item id, when fetched expanded.",
"example": "li_8f14e45fceea467f"
},
"metadata": {
"type": "object",
"description": "The book's metadata.",
"required": [
"title",
"titleIgnorePrefix",
"authors",
"authorName",
"authorNameLF",
"narrators",
"narratorName",
"series",
"seriesName",
"genres",
"explicit",
"abridged"
],
"properties": {
"title": {
"type": "string",
"description": "The title.",
"example": "The First"
},
"titleIgnorePrefix": {
"type": "string",
"description": "The title for sorting.",
"example": "First, The"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "The subtitle, if any.",
"example": "A Novel"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"description": "An id and a name.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its display name.",
"example": "Ann Author"
}
}
},
"description": "The authors."
},
"authorName": {
"type": "string",
"description": "The authors' names joined with `, `.",
"example": "Ann Author"
},
"authorNameLF": {
"type": "string",
"description": "The authors' names, family name first, joined with `, `.",
"example": "Author, Ann"
},
"narrators": {
"type": "array",
"items": {
"type": "string"
},
"description": "The narrators' names.",
"example": [
"Nia Narrator"
]
},
"narratorName": {
"type": "string",
"description": "The narrators' names joined with `, `.",
"example": "Nia Narrator"
},
"series": {
"type": "array",
"items": {
"type": "object",
"description": "A series an item belongs to, with the item's place in it.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The series name.",
"example": "Ann Author"
},
"sequence": {
"type": [
"string",
"null"
],
"description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
"example": "1"
}
}
},
"description": "The series the book is in."
},
"seriesName": {
"type": "string",
"description": "The series names with the book's place (`Name #2`), joined.",
"example": "The Saga #1"
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"description": "Genres.",
"example": [
"Fantasy"
]
},
"publishedYear": {
"type": [
"string",
"null"
],
"description": "The year of publication, as a string (`\"2019\"`).",
"example": "2024"
},
"publishedDate": {
"type": [
"string",
"null"
],
"description": "The date of publication, if known.",
"example": "2024-03-01"
},
"publisher": {
"type": [
"string",
"null"
],
"description": "The publisher.",
"example": "Example Press"
},
"description": {
"type": [
"string",
"null"
],
"description": "The description, as the library stores it.",
"example": "A short description."
},
"descriptionPlain": {
"type": [
"string",
"null"
],
"description": "The description with markup removed.",
"example": "A short description."
},
"isbn": {
"type": [
"string",
"null"
],
"description": "The ISBN, if known.",
"example": "9780000000002"
},
"asin": {
"type": [
"string",
"null"
],
"description": "The ASIN, if known.",
"example": "B000000000"
},
"language": {
"type": [
"string",
"null"
],
"description": "The language.",
"example": "en-us"
},
"explicit": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"abridged": {
"type": "boolean",
"description": "Whether the edition is abridged.",
"example": false
}
}
},
"coverPath": {
"type": [
"string",
"null"
],
"description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
"example": "/player/api/items/li_8f14e45fceea467f/cover"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags: none.",
"example": []
},
"numTracks": {
"type": "integer",
"format": "int64",
"description": "Tracks in play order.",
"example": 1,
"minimum": 0
},
"numAudioFiles": {
"type": "integer",
"format": "int64",
"description": "Audio files.",
"example": 1,
"minimum": 0
},
"numChapters": {
"type": "integer",
"format": "int64",
"description": "Chapters.",
"example": 0,
"minimum": 0
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds.",
"example": 36000.0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in its audio files.",
"example": 100000,
"minimum": 0
},
"audioFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "An audio file of a book.",
"required": [
"index",
"ino",
"metadata",
"addedAt",
"updatedAt",
"manuallyVerified",
"exclude",
"duration",
"chapters",
"metaTags",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The file's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"trackNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number the file's tags state: not read.",
"example": 1,
"minimum": 0
},
"discNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number the file's tags state: not read.",
"example": null,
"minimum": 0
},
"trackNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number in the file name: not read.",
"example": null,
"minimum": 0
},
"discNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number in the file name: not read.",
"example": null,
"minimum": 0
},
"manuallyVerified": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"exclude": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"error": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"format": {
"type": [
"string",
"null"
],
"description": "The container format, such as `mp4` or `mp3`.",
"example": "MP4A"
},
"duration": {
"type": "number",
"format": "double",
"description": "The file's length in seconds.",
"example": 36000.0
},
"bitRate": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Bits per second, if known.",
"example": 128000,
"minimum": 0
},
"language": {
"type": [
"string",
"null"
],
"description": "The file's language, if known.",
"example": "en-us"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"timeBase": {
"type": [
"string",
"null"
],
"description": "The time base, if known.",
"example": "1/44100"
},
"channels": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Audio channels, if known.",
"example": 2,
"minimum": 0
},
"channelLayout": {
"type": [
"string",
"null"
],
"description": "The channel layout, if known.",
"example": "stereo"
},
"chapters": {
"type": "array",
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "Chapters embedded in the file: none are read."
},
"embeddedCoverArt": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"metaTags": {
"type": "object",
"description": "Tags read from the file: none until the stored media probe reads\nthem."
},
"mimeType": {
"type": "string",
"description": "The file's media type, such as `audio/mp4`.",
"example": "audio/mp4"
}
}
},
"description": "The audio files, when fetched expanded."
},
"chapters": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "The chapters, when fetched expanded."
},
"tracks": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A track with its place in the book.",
"required": [
"index",
"startOffset",
"duration",
"title",
"contentUrl",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The track's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"startOffset": {
"type": "number",
"format": "double",
"description": "Where the track starts in the book, in seconds.",
"example": 0.0
},
"duration": {
"type": "number",
"format": "double",
"description": "The track's length in seconds.",
"example": 36000.0
},
"title": {
"type": "string",
"description": "The track's title: its file name.",
"example": "The First"
},
"contentUrl": {
"type": "string",
"description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
"example": "/player/api/items/li_8f14e45fceea467f/file/0"
},
"mimeType": {
"type": "string",
"description": "The track's media type.",
"example": "audio/mp4"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"metadata": {
"oneOf": [
{
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "The tracks with their place in the book, when fetched expanded."
}
}
},
"numFiles": {
"type": "integer",
"format": "int64",
"description": "Files in the item.",
"example": 1,
"minimum": 0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in all its files.",
"example": 100000,
"minimum": 0
},
"libraryFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A file of an item, in the expanded item's `libraryFiles`.",
"required": [
"ino",
"metadata",
"addedAt",
"updatedAt",
"fileType"
],
"properties": {
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"fileType": {
"type": "string",
"description": "Always `audio`.",
"example": "audio"
}
}
},
"description": "The item's files, when the item is fetched expanded."
},
"userMediaProgress": {
"oneOf": [
{
"type": "object",
"description": "The patron's progress, when the app asked for it.",
"required": [
"id",
"userId",
"libraryItemId",
"mediaItemId",
"mediaItemType",
"duration",
"progress",
"currentTime",
"isFinished",
"hideFromContinueListening",
"lastUpdate",
"startedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The progress id: the item id (one record per patron and item).",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaItemId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"mediaItemType": {
"type": "string",
"description": "Always `book`.",
"example": "book"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds, as last reported.",
"example": 36000.0
},
"progress": {
"type": "number",
"format": "double",
"description": "The share listened, from 0 to 1.",
"example": 0.05
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished it.",
"example": false
},
"hideFromContinueListening": {
"type": "boolean",
"description": "Whether it is hidden from continue listening.",
"example": false
},
"ebookLocation": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"ebookProgress": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Always null.",
"example": null
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When the progress last changed, in epoch milliseconds.",
"example": 1763630000000
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the patron started, in epoch milliseconds.",
"example": 1763620000000
},
"finishedAt": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron finished, in epoch milliseconds.",
"example": null
}
}
},
{
"type": "null"
}
]
},
"seriesSequence": {
"type": [
"string",
"null"
],
"description": "The item's place in a series, on a series' book list.",
"example": "1"
}
}
}
Status 400: A query value is out of range.
Bad Request
Schema:
A text/plain body: a string.
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 404: No such item the patron may see.
Not Found
Schema:
A text/plain body: a string.
Status 500: The library could not be read.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Reads several items at once.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
The items to read, at most 100.
application/json: BatchGetBody
libraryItemIdsarray of stringrequiredThe items, at most 100.
-
200The items the patron may see, in the given order. Body:
LibraryItems(application/json)1 fieldlibraryItemsarray ofLibraryItemrequiredThe items.
- 400The body is malformed. As
text/plain, when the body is not syntactically valid JSON. Body: string (text/plain) - 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 413The body is too long. Body: string (
text/plain) - 415The request did not declare a JSON body. Body: string (
text/plain) - 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (
text/plain) - 500The library could not be read. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/items/batch/get' \
-X POST \
-H 'Authorization: Bearer <playerToken>' \
-H 'Content-Type: application/json' \
-d '{"libraryItemIds": ["li_8f14e45fceea467f"]}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/items/batch/get' `
-Method Post `
-Headers @{ Authorization = 'Bearer <playerToken>' } `
-ContentType 'application/json' `
-Body '{"libraryItemIds": ["li_8f14e45fceea467f"]}'
import requests
response = requests.post(
"http://127.0.0.1:8787/player/api/items/batch/get",
headers={"Authorization": "Bearer <playerToken>"},
json={"libraryItemIds": ["li_8f14e45fceea467f"]},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/items/batch/get", {
method: "POST",
headers: { Authorization: "Bearer <playerToken>", "Content-Type": "application/json" },
body: JSON.stringify({"libraryItemIds": ["li_8f14e45fceea467f"]}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/player/api/items/batch/get")
.header("Authorization", "Bearer <playerToken>")
.json(&serde_json::json!({"libraryItemIds": ["li_8f14e45fceea467f"]}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The items the patron may see, in the given order.
{
"libraryItems": [
{
"id": "li_8f14e45fceea467f",
"ino": "0",
"oldLibraryItemId": null,
"libraryId": "bookclerk-library",
"folderId": "bookclerk-library",
"path": "/the-first.m4b",
"relPath": "the-first.m4b",
"isFile": true,
"mtimeMs": 1763600000000,
"ctimeMs": 1763600000000,
"birthtimeMs": 1763600000000,
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"isMissing": false,
"isInvalid": false,
"mediaType": "book",
"media": {
"id": "li_8f14e45fceea467f",
"libraryItemId": "li_8f14e45fceea467f",
"metadata": {
"title": "The First",
"titleIgnorePrefix": "First, The",
"authors": [],
"authorName": "Ann Author",
"authorNameLF": "Author, Ann",
"narrators": [
"Nia Narrator"
],
"narratorName": "Nia Narrator",
"series": [],
"seriesName": "The Saga #1",
"genres": [
"Fantasy"
],
"explicit": false,
"abridged": false
},
"coverPath": "/player/api/items/li_8f14e45fceea467f/cover",
"tags": [],
"numTracks": 1,
"numAudioFiles": 1,
"numChapters": 0,
"duration": 36000.0,
"size": 100000,
"audioFiles": [],
"chapters": [],
"tracks": []
},
"numFiles": 1,
"size": 100000,
"libraryFiles": [
{
"ino": "0",
"metadata": {
"filename": "the-first.m4b",
"ext": ".m4b",
"path": "/the-first.m4b",
"relPath": "the-first.m4b",
"size": 100000,
"mtimeMs": 1763600000000,
"ctimeMs": 1763600000000,
"birthtimeMs": 1763600000000
},
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"fileType": "audio"
}
],
"userMediaProgress": {
"id": "li_8f14e45fceea467f",
"userId": "42",
"libraryItemId": "li_8f14e45fceea467f",
"episodeId": null,
"mediaItemId": "li_8f14e45fceea467f",
"mediaItemType": "book",
"duration": 36000.0,
"progress": 0.05,
"currentTime": 1830.5,
"isFinished": false,
"hideFromContinueListening": false,
"ebookLocation": null,
"ebookProgress": null,
"lastUpdate": 1763630000000,
"startedAt": 1763620000000,
"finishedAt": null
},
"seriesSequence": "1"
}
]
}
Schema:
{
"type": "object",
"description": "`{ \"libraryItems\": [...] }`: in-progress items and batch reads.",
"required": [
"libraryItems"
],
"properties": {
"libraryItems": {
"type": "array",
"items": {
"type": "object",
"description": "An item: an edition with a stored copy.",
"required": [
"id",
"ino",
"libraryId",
"folderId",
"path",
"relPath",
"isFile",
"mtimeMs",
"ctimeMs",
"birthtimeMs",
"addedAt",
"updatedAt",
"isMissing",
"isInvalid",
"mediaType",
"media",
"numFiles",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The item id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"ino": {
"type": "string",
"description": "The item's inode as apps expect one: the edition id again.",
"example": "0"
},
"oldLibraryItemId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"libraryId": {
"type": "string",
"description": "The library the item is listed in.",
"example": "bookclerk-library"
},
"folderId": {
"type": "string",
"description": "The folder id: the library id.",
"example": "bookclerk-library"
},
"path": {
"type": "string",
"description": "A display path: the title.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the title.",
"example": "the-first.m4b"
},
"isFile": {
"type": "boolean",
"description": "Always false: an item is a folder of tracks.",
"example": true
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy last changed, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the item joined the library, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When its record last changed, in epoch milliseconds.",
"example": 1763630000000
},
"isMissing": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"isInvalid": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"mediaType": {
"type": "string",
"description": "Always [`MEDIA_TYPE_BOOK`].",
"example": "book"
},
"media": {
"type": "object",
"description": "The book.",
"required": [
"id",
"metadata",
"tags",
"numTracks",
"numAudioFiles",
"numChapters",
"duration",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The media id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"libraryItemId": {
"type": [
"string",
"null"
],
"description": "The item id, when fetched expanded.",
"example": "li_8f14e45fceea467f"
},
"metadata": {
"type": "object",
"description": "The book's metadata.",
"required": [
"title",
"titleIgnorePrefix",
"authors",
"authorName",
"authorNameLF",
"narrators",
"narratorName",
"series",
"seriesName",
"genres",
"explicit",
"abridged"
],
"properties": {
"title": {
"type": "string",
"description": "The title.",
"example": "The First"
},
"titleIgnorePrefix": {
"type": "string",
"description": "The title for sorting.",
"example": "First, The"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "The subtitle, if any.",
"example": "A Novel"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"description": "An id and a name.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its display name.",
"example": "Ann Author"
}
}
},
"description": "The authors."
},
"authorName": {
"type": "string",
"description": "The authors' names joined with `, `.",
"example": "Ann Author"
},
"authorNameLF": {
"type": "string",
"description": "The authors' names, family name first, joined with `, `.",
"example": "Author, Ann"
},
"narrators": {
"type": "array",
"items": {
"type": "string"
},
"description": "The narrators' names.",
"example": [
"Nia Narrator"
]
},
"narratorName": {
"type": "string",
"description": "The narrators' names joined with `, `.",
"example": "Nia Narrator"
},
"series": {
"type": "array",
"items": {
"type": "object",
"description": "A series an item belongs to, with the item's place in it.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The series name.",
"example": "Ann Author"
},
"sequence": {
"type": [
"string",
"null"
],
"description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
"example": "1"
}
}
},
"description": "The series the book is in."
},
"seriesName": {
"type": "string",
"description": "The series names with the book's place (`Name #2`), joined.",
"example": "The Saga #1"
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"description": "Genres.",
"example": [
"Fantasy"
]
},
"publishedYear": {
"type": [
"string",
"null"
],
"description": "The year of publication, as a string (`\"2019\"`).",
"example": "2024"
},
"publishedDate": {
"type": [
"string",
"null"
],
"description": "The date of publication, if known.",
"example": "2024-03-01"
},
"publisher": {
"type": [
"string",
"null"
],
"description": "The publisher.",
"example": "Example Press"
},
"description": {
"type": [
"string",
"null"
],
"description": "The description, as the library stores it.",
"example": "A short description."
},
"descriptionPlain": {
"type": [
"string",
"null"
],
"description": "The description with markup removed.",
"example": "A short description."
},
"isbn": {
"type": [
"string",
"null"
],
"description": "The ISBN, if known.",
"example": "9780000000002"
},
"asin": {
"type": [
"string",
"null"
],
"description": "The ASIN, if known.",
"example": "B000000000"
},
"language": {
"type": [
"string",
"null"
],
"description": "The language.",
"example": "en-us"
},
"explicit": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"abridged": {
"type": "boolean",
"description": "Whether the edition is abridged.",
"example": false
}
}
},
"coverPath": {
"type": [
"string",
"null"
],
"description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
"example": "/player/api/items/li_8f14e45fceea467f/cover"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags: none.",
"example": []
},
"numTracks": {
"type": "integer",
"format": "int64",
"description": "Tracks in play order.",
"example": 1,
"minimum": 0
},
"numAudioFiles": {
"type": "integer",
"format": "int64",
"description": "Audio files.",
"example": 1,
"minimum": 0
},
"numChapters": {
"type": "integer",
"format": "int64",
"description": "Chapters.",
"example": 0,
"minimum": 0
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds.",
"example": 36000.0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in its audio files.",
"example": 100000,
"minimum": 0
},
"audioFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "An audio file of a book.",
"required": [
"index",
"ino",
"metadata",
"addedAt",
"updatedAt",
"manuallyVerified",
"exclude",
"duration",
"chapters",
"metaTags",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The file's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"trackNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number the file's tags state: not read.",
"example": 1,
"minimum": 0
},
"discNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number the file's tags state: not read.",
"example": null,
"minimum": 0
},
"trackNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number in the file name: not read.",
"example": null,
"minimum": 0
},
"discNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number in the file name: not read.",
"example": null,
"minimum": 0
},
"manuallyVerified": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"exclude": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"error": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"format": {
"type": [
"string",
"null"
],
"description": "The container format, such as `mp4` or `mp3`.",
"example": "MP4A"
},
"duration": {
"type": "number",
"format": "double",
"description": "The file's length in seconds.",
"example": 36000.0
},
"bitRate": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Bits per second, if known.",
"example": 128000,
"minimum": 0
},
"language": {
"type": [
"string",
"null"
],
"description": "The file's language, if known.",
"example": "en-us"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"timeBase": {
"type": [
"string",
"null"
],
"description": "The time base, if known.",
"example": "1/44100"
},
"channels": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Audio channels, if known.",
"example": 2,
"minimum": 0
},
"channelLayout": {
"type": [
"string",
"null"
],
"description": "The channel layout, if known.",
"example": "stereo"
},
"chapters": {
"type": "array",
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "Chapters embedded in the file: none are read."
},
"embeddedCoverArt": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"metaTags": {
"type": "object",
"description": "Tags read from the file: none until the stored media probe reads\nthem."
},
"mimeType": {
"type": "string",
"description": "The file's media type, such as `audio/mp4`.",
"example": "audio/mp4"
}
}
},
"description": "The audio files, when fetched expanded."
},
"chapters": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "The chapters, when fetched expanded."
},
"tracks": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A track with its place in the book.",
"required": [
"index",
"startOffset",
"duration",
"title",
"contentUrl",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The track's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"startOffset": {
"type": "number",
"format": "double",
"description": "Where the track starts in the book, in seconds.",
"example": 0.0
},
"duration": {
"type": "number",
"format": "double",
"description": "The track's length in seconds.",
"example": 36000.0
},
"title": {
"type": "string",
"description": "The track's title: its file name.",
"example": "The First"
},
"contentUrl": {
"type": "string",
"description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
"example": "/player/api/items/li_8f14e45fceea467f/file/0"
},
"mimeType": {
"type": "string",
"description": "The track's media type.",
"example": "audio/mp4"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"metadata": {
"oneOf": [
{
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "The tracks with their place in the book, when fetched expanded."
}
}
},
"numFiles": {
"type": "integer",
"format": "int64",
"description": "Files in the item.",
"example": 1,
"minimum": 0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in all its files.",
"example": 100000,
"minimum": 0
},
"libraryFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A file of an item, in the expanded item's `libraryFiles`.",
"required": [
"ino",
"metadata",
"addedAt",
"updatedAt",
"fileType"
],
"properties": {
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"fileType": {
"type": "string",
"description": "Always `audio`.",
"example": "audio"
}
}
},
"description": "The item's files, when the item is fetched expanded."
},
"userMediaProgress": {
"oneOf": [
{
"type": "object",
"description": "The patron's progress, when the app asked for it.",
"required": [
"id",
"userId",
"libraryItemId",
"mediaItemId",
"mediaItemType",
"duration",
"progress",
"currentTime",
"isFinished",
"hideFromContinueListening",
"lastUpdate",
"startedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The progress id: the item id (one record per patron and item).",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaItemId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"mediaItemType": {
"type": "string",
"description": "Always `book`.",
"example": "book"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds, as last reported.",
"example": 36000.0
},
"progress": {
"type": "number",
"format": "double",
"description": "The share listened, from 0 to 1.",
"example": 0.05
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished it.",
"example": false
},
"hideFromContinueListening": {
"type": "boolean",
"description": "Whether it is hidden from continue listening.",
"example": false
},
"ebookLocation": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"ebookProgress": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Always null.",
"example": null
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When the progress last changed, in epoch milliseconds.",
"example": 1763630000000
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the patron started, in epoch milliseconds.",
"example": 1763620000000
},
"finishedAt": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron finished, in epoch milliseconds.",
"example": null
}
}
},
{
"type": "null"
}
]
},
"seriesSequence": {
"type": [
"string",
"null"
],
"description": "The item's place in a series, on a series' book list.",
"example": "1"
}
}
},
"description": "The items."
}
}
}
Status 400: The body is malformed. As text/plain, when the body is not syntactically valid JSON.
Failed to parse the request body as JSON: expected value at line 1 column 1
Schema:
A text/plain body: a string.
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 413: The body is too long.
Payload Too Large
Schema:
A text/plain body: a string.
Status 415: The request did not declare a JSON body.
Expected request with `Content-Type: application/json`
Schema:
A text/plain body: a string.
Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.
Failed to deserialize the JSON body into the target type: missing field `libraryItemIds` at line 1 column 2
Schema:
A text/plain body: a string.
Status 500: The library could not be read.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Serves an item's cover.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
idpathstringrequiredItem id.
- 200The cover. Body: binary (
image/jpeg) - 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 404No such item, or no cover of it on this node. Body: string (
text/plain) - 500The library or the cover could not be read. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/items/<id>/cover' \
-H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/items/<id>/cover' `
-Headers @{ Authorization = 'Bearer <playerToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/player/api/items/<id>/cover",
headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/items/<id>/cover", {
headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/player/api/items/<id>/cover")
.header("Authorization", "Bearer <playerToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The cover. The body is binary (image/jpeg).
Schema:
A image/jpeg body: binary bytes.
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 404: No such item, or no cover of it on this node.
Not Found
Schema:
A text/plain body: a string.
Status 500: The library or the cover could not be read.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Opens a play session on an item.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
idpathstringrequiredItem id.
The device and what the app asks for; tracks always play directly.
application/json: PlayBody
deviceInfoDeviceInfoBodyor nullThe device, named in the patron's session list.forceDirectPlayboolean or nullWhether the app asks for direct play; tracks always play directly.forceTranscodeboolean or nullWhether the app asks for transcoding; it gets direct tracks too.mediaPlayerstring or nullThe app's player, shown in the session list.
-
200The session, its tracks and where to start. Body:
PlaybackSession(application/json)26 fieldsidstringrequiredThe session id; apps send it back to sync and close.userIdstringrequiredThe patron's id.libraryIdstringrequiredThe library id.libraryItemIdstringrequiredThe item id.bookIdstringrequiredThe media id: the item id.episodeIdstring or nullAlways null.mediaTypestringrequiredAlways [MEDIA_TYPE_BOOK].mediaMetadataBookMetadatarequiredThe book's metadata.chaptersarray ofChapterrequiredThe book's chapters.displayTitlestringrequiredThe title apps show.displayAuthorstringrequiredThe author apps show.coverPathstring or nullA cover path apps test for presence.durationnumber (double)requiredThe book's length in seconds.playMethodinteger (int32)requiredHow the app plays: 0, direct play of the stored files. At least 0.mediaPlayerstringrequiredThe player the app reported.deviceInfoSessionDevicerequiredThe device the session was opened from.serverVersionstringrequired[crate::COMPATIBLE_SERVER_VERSION].datestringrequiredThe day the session started,YYYY-MM-DDin UTC.dayOfWeekstringrequiredThe weekday the session started, in English.timeListeningnumber (double)requiredSeconds listened in this session.startTimenumber (double)requiredWhere the session started, in seconds.currentTimenumber (double)requiredWhere the patron is, in seconds.startedAtinteger (int64)requiredWhen the session started, in epoch milliseconds.updatedAtinteger (int64)requiredWhen it last synced, in epoch milliseconds.audioTracksarray ofAudioTrackrequiredThe tracks to play, in order.libraryItemLibraryItemor nullThe item, expanded.
- 400The body is malformed. As
text/plain, when the body is not syntactically valid JSON. Body: string (text/plain) - 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 404No such item, or nothing of it this patron may play here. Body: string (
text/plain) - 413The body is too long. Body: string (
text/plain) - 415The request did not declare a JSON body. Body: string (
text/plain) - 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (
text/plain) - 500The library could not be read or written. Body: string (
text/plain) - 503Storage could not be asked; retry. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/items/<id>/play' \
-X POST \
-H 'Authorization: Bearer <playerToken>' \
-H 'Content-Type: application/json' \
-d '{}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/items/<id>/play' `
-Method Post `
-Headers @{ Authorization = 'Bearer <playerToken>' } `
-ContentType 'application/json' `
-Body '{}'
import requests
response = requests.post(
"http://127.0.0.1:8787/player/api/items/<id>/play",
headers={"Authorization": "Bearer <playerToken>"},
json={},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/items/<id>/play", {
method: "POST",
headers: { Authorization: "Bearer <playerToken>", "Content-Type": "application/json" },
body: JSON.stringify({}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/player/api/items/<id>/play")
.header("Authorization", "Bearer <playerToken>")
.json(&serde_json::json!({}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The session, its tracks and where to start.
{
"id": "li_8f14e45fceea467f",
"userId": "42",
"libraryId": "bookclerk-library",
"libraryItemId": "li_8f14e45fceea467f",
"bookId": "li_8f14e45fceea467f",
"episodeId": null,
"mediaType": "book",
"mediaMetadata": {
"title": "The First",
"titleIgnorePrefix": "First, The",
"subtitle": "A Novel",
"authors": [
{
"id": "li_8f14e45fceea467f",
"name": "Ann Author"
}
],
"authorName": "Ann Author",
"authorNameLF": "Author, Ann",
"narrators": [
"Nia Narrator"
],
"narratorName": "Nia Narrator",
"series": [
{
"id": "li_8f14e45fceea467f",
"name": "Ann Author",
"sequence": "1"
}
],
"seriesName": "The Saga #1",
"genres": [
"Fantasy"
],
"publishedYear": "2024",
"publishedDate": "2024-03-01",
"publisher": "Example Press",
"description": "A short description.",
"descriptionPlain": "A short description.",
"isbn": "9780000000002",
"asin": "B000000000",
"language": "en-us",
"explicit": false,
"abridged": false
},
"chapters": [
{
"id": 1,
"start": 0.0,
"end": 600.0,
"title": "The First"
}
],
"displayTitle": "The First",
"displayAuthor": "Ann Author",
"coverPath": "/player/api/items/li_8f14e45fceea467f/cover",
"duration": 36000.0,
"playMethod": 1,
"mediaPlayer": "Absorb",
"deviceInfo": {
"deviceId": "pixel-8",
"deviceName": "Pixel 8",
"clientName": "Absorb"
},
"serverVersion": "2.17.0",
"date": "2026-11-20",
"dayOfWeek": "Friday",
"timeListening": 60.0,
"startTime": 1770.5,
"currentTime": 1830.5,
"startedAt": 1763620000000,
"updatedAt": 1763630000000,
"audioTracks": [
{
"index": 1,
"startOffset": 0.0,
"duration": 36000.0,
"title": "The First",
"contentUrl": "/player/api/items/li_8f14e45fceea467f/file/0",
"mimeType": "audio/mp4",
"codec": "aac",
"metadata": {
"filename": "the-first.m4b",
"ext": ".m4b",
"path": "/the-first.m4b",
"relPath": "the-first.m4b",
"size": 100000,
"mtimeMs": 1763600000000,
"ctimeMs": 1763600000000,
"birthtimeMs": 1763600000000
}
}
],
"libraryItem": {
"id": "li_8f14e45fceea467f",
"ino": "0",
"oldLibraryItemId": null,
"libraryId": "bookclerk-library",
"folderId": "bookclerk-library",
"path": "/the-first.m4b",
"relPath": "the-first.m4b",
"isFile": true,
"mtimeMs": 1763600000000,
"ctimeMs": 1763600000000,
"birthtimeMs": 1763600000000,
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"isMissing": false,
"isInvalid": false,
"mediaType": "book",
"media": {
"id": "li_8f14e45fceea467f",
"libraryItemId": "li_8f14e45fceea467f",
"metadata": {
"title": "The First",
"titleIgnorePrefix": "First, The",
"subtitle": "A Novel",
"authors": [],
"authorName": "Ann Author",
"authorNameLF": "Author, Ann",
"narrators": [
"Nia Narrator"
],
"narratorName": "Nia Narrator",
"series": [],
"seriesName": "The Saga #1",
"genres": [
"Fantasy"
],
"publishedYear": "2024",
"publishedDate": "2024-03-01",
"publisher": "Example Press",
"description": "A short description.",
"descriptionPlain": "A short description.",
"isbn": "9780000000002",
"asin": "B000000000",
"language": "en-us",
"explicit": false,
"abridged": false
},
"coverPath": "/player/api/items/li_8f14e45fceea467f/cover",
"tags": [],
"numTracks": 1,
"numAudioFiles": 1,
"numChapters": 0,
"duration": 36000.0,
"size": 100000,
"audioFiles": [
{
"index": 1,
"ino": "0",
"metadata": {
"filename": "the-first.m4b",
"ext": ".m4b",
"path": "/the-first.m4b",
"relPath": "the-first.m4b",
"size": 100000,
"mtimeMs": 1763600000000,
"ctimeMs": 1763600000000,
"birthtimeMs": 1763600000000
},
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"manuallyVerified": false,
"exclude": false,
"duration": 36000.0,
"chapters": [],
"metaTags": {},
"mimeType": "audio/mp4"
}
],
"chapters": [
{
"id": 1,
"start": 0.0,
"end": 600.0,
"title": "The First"
}
],
"tracks": [
{
"index": 1,
"startOffset": 0.0,
"duration": 36000.0,
"title": "The First",
"contentUrl": "/player/api/items/li_8f14e45fceea467f/file/0",
"mimeType": "audio/mp4"
}
]
},
"numFiles": 1,
"size": 100000,
"libraryFiles": [
{
"ino": "0",
"metadata": {
"filename": "the-first.m4b",
"ext": ".m4b",
"path": "/the-first.m4b",
"relPath": "the-first.m4b",
"size": 100000,
"mtimeMs": 1763600000000,
"ctimeMs": 1763600000000,
"birthtimeMs": 1763600000000
},
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"fileType": "audio"
}
],
"userMediaProgress": {
"id": "li_8f14e45fceea467f",
"userId": "42",
"libraryItemId": "li_8f14e45fceea467f",
"episodeId": null,
"mediaItemId": "li_8f14e45fceea467f",
"mediaItemType": "book",
"duration": 36000.0,
"progress": 0.05,
"currentTime": 1830.5,
"isFinished": false,
"hideFromContinueListening": false,
"ebookLocation": null,
"ebookProgress": null,
"lastUpdate": 1763630000000,
"startedAt": 1763620000000,
"finishedAt": null
},
"seriesSequence": "1"
}
}
Schema:
{
"type": "object",
"description": "A playback session, as `POST /api/items/{id}/play` answers.",
"required": [
"id",
"userId",
"libraryId",
"libraryItemId",
"bookId",
"mediaType",
"mediaMetadata",
"chapters",
"displayTitle",
"displayAuthor",
"duration",
"playMethod",
"mediaPlayer",
"deviceInfo",
"serverVersion",
"date",
"dayOfWeek",
"timeListening",
"startTime",
"currentTime",
"startedAt",
"updatedAt",
"audioTracks"
],
"properties": {
"id": {
"type": "string",
"description": "The session id; apps send it back to sync and close.",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryId": {
"type": "string",
"description": "The library id.",
"example": "bookclerk-library"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"bookId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaType": {
"type": "string",
"description": "Always [`MEDIA_TYPE_BOOK`].",
"example": "book"
},
"mediaMetadata": {
"type": "object",
"description": "The book's metadata.",
"required": [
"title",
"titleIgnorePrefix",
"authors",
"authorName",
"authorNameLF",
"narrators",
"narratorName",
"series",
"seriesName",
"genres",
"explicit",
"abridged"
],
"properties": {
"title": {
"type": "string",
"description": "The title.",
"example": "The First"
},
"titleIgnorePrefix": {
"type": "string",
"description": "The title for sorting.",
"example": "First, The"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "The subtitle, if any.",
"example": "A Novel"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"description": "An id and a name.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its display name.",
"example": "Ann Author"
}
}
},
"description": "The authors."
},
"authorName": {
"type": "string",
"description": "The authors' names joined with `, `.",
"example": "Ann Author"
},
"authorNameLF": {
"type": "string",
"description": "The authors' names, family name first, joined with `, `.",
"example": "Author, Ann"
},
"narrators": {
"type": "array",
"items": {
"type": "string"
},
"description": "The narrators' names.",
"example": [
"Nia Narrator"
]
},
"narratorName": {
"type": "string",
"description": "The narrators' names joined with `, `.",
"example": "Nia Narrator"
},
"series": {
"type": "array",
"items": {
"type": "object",
"description": "A series an item belongs to, with the item's place in it.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The series name.",
"example": "Ann Author"
},
"sequence": {
"type": [
"string",
"null"
],
"description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
"example": "1"
}
}
},
"description": "The series the book is in."
},
"seriesName": {
"type": "string",
"description": "The series names with the book's place (`Name #2`), joined.",
"example": "The Saga #1"
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"description": "Genres.",
"example": [
"Fantasy"
]
},
"publishedYear": {
"type": [
"string",
"null"
],
"description": "The year of publication, as a string (`\"2019\"`).",
"example": "2024"
},
"publishedDate": {
"type": [
"string",
"null"
],
"description": "The date of publication, if known.",
"example": "2024-03-01"
},
"publisher": {
"type": [
"string",
"null"
],
"description": "The publisher.",
"example": "Example Press"
},
"description": {
"type": [
"string",
"null"
],
"description": "The description, as the library stores it.",
"example": "A short description."
},
"descriptionPlain": {
"type": [
"string",
"null"
],
"description": "The description with markup removed.",
"example": "A short description."
},
"isbn": {
"type": [
"string",
"null"
],
"description": "The ISBN, if known.",
"example": "9780000000002"
},
"asin": {
"type": [
"string",
"null"
],
"description": "The ASIN, if known.",
"example": "B000000000"
},
"language": {
"type": [
"string",
"null"
],
"description": "The language.",
"example": "en-us"
},
"explicit": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"abridged": {
"type": "boolean",
"description": "Whether the edition is abridged.",
"example": false
}
}
},
"chapters": {
"type": "array",
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "The book's chapters."
},
"displayTitle": {
"type": "string",
"description": "The title apps show.",
"example": "The First"
},
"displayAuthor": {
"type": "string",
"description": "The author apps show.",
"example": "Ann Author"
},
"coverPath": {
"type": [
"string",
"null"
],
"description": "A cover path apps test for presence.",
"example": "/player/api/items/li_8f14e45fceea467f/cover"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds.",
"example": 36000.0
},
"playMethod": {
"type": "integer",
"format": "int32",
"description": "How the app plays: 0, direct play of the stored files.",
"example": 1,
"minimum": 0
},
"mediaPlayer": {
"type": "string",
"description": "The player the app reported.",
"example": "Absorb"
},
"deviceInfo": {
"type": "object",
"description": "The device the session was opened from.",
"required": [
"deviceId"
],
"properties": {
"deviceId": {
"type": "string",
"description": "The device's id: the card's session id.",
"example": "pixel-8"
},
"deviceName": {
"type": [
"string",
"null"
],
"description": "The device name the app reported, if any.",
"example": "Pixel 8"
},
"clientName": {
"type": [
"string",
"null"
],
"description": "The app's name, if reported.",
"example": "Absorb"
}
}
},
"serverVersion": {
"type": "string",
"description": "[`crate::COMPATIBLE_SERVER_VERSION`].",
"example": "2.17.0"
},
"date": {
"type": "string",
"description": "The day the session started, `YYYY-MM-DD` in UTC.",
"example": "2026-11-20"
},
"dayOfWeek": {
"type": "string",
"description": "The weekday the session started, in English.",
"example": "Friday"
},
"timeListening": {
"type": "number",
"format": "double",
"description": "Seconds listened in this session.",
"example": 60.0
},
"startTime": {
"type": "number",
"format": "double",
"description": "Where the session started, in seconds.",
"example": 1770.5
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the session started, in epoch milliseconds.",
"example": 1763620000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When it last synced, in epoch milliseconds.",
"example": 1763630000000
},
"audioTracks": {
"type": "array",
"items": {
"type": "object",
"description": "A track with its place in the book.",
"required": [
"index",
"startOffset",
"duration",
"title",
"contentUrl",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The track's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"startOffset": {
"type": "number",
"format": "double",
"description": "Where the track starts in the book, in seconds.",
"example": 0.0
},
"duration": {
"type": "number",
"format": "double",
"description": "The track's length in seconds.",
"example": 36000.0
},
"title": {
"type": "string",
"description": "The track's title: its file name.",
"example": "The First"
},
"contentUrl": {
"type": "string",
"description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
"example": "/player/api/items/li_8f14e45fceea467f/file/0"
},
"mimeType": {
"type": "string",
"description": "The track's media type.",
"example": "audio/mp4"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"metadata": {
"oneOf": [
{
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "The tracks to play, in order."
},
"libraryItem": {
"oneOf": [
{
"type": "object",
"description": "The item, expanded.",
"required": [
"id",
"ino",
"libraryId",
"folderId",
"path",
"relPath",
"isFile",
"mtimeMs",
"ctimeMs",
"birthtimeMs",
"addedAt",
"updatedAt",
"isMissing",
"isInvalid",
"mediaType",
"media",
"numFiles",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The item id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"ino": {
"type": "string",
"description": "The item's inode as apps expect one: the edition id again.",
"example": "0"
},
"oldLibraryItemId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"libraryId": {
"type": "string",
"description": "The library the item is listed in.",
"example": "bookclerk-library"
},
"folderId": {
"type": "string",
"description": "The folder id: the library id.",
"example": "bookclerk-library"
},
"path": {
"type": "string",
"description": "A display path: the title.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the title.",
"example": "the-first.m4b"
},
"isFile": {
"type": "boolean",
"description": "Always false: an item is a folder of tracks.",
"example": true
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy last changed, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the item joined the library, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When its record last changed, in epoch milliseconds.",
"example": 1763630000000
},
"isMissing": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"isInvalid": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"mediaType": {
"type": "string",
"description": "Always [`MEDIA_TYPE_BOOK`].",
"example": "book"
},
"media": {
"type": "object",
"description": "The book.",
"required": [
"id",
"metadata",
"tags",
"numTracks",
"numAudioFiles",
"numChapters",
"duration",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The media id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"libraryItemId": {
"type": [
"string",
"null"
],
"description": "The item id, when fetched expanded.",
"example": "li_8f14e45fceea467f"
},
"metadata": {
"type": "object",
"description": "The book's metadata.",
"required": [
"title",
"titleIgnorePrefix",
"authors",
"authorName",
"authorNameLF",
"narrators",
"narratorName",
"series",
"seriesName",
"genres",
"explicit",
"abridged"
],
"properties": {
"title": {
"type": "string",
"description": "The title.",
"example": "The First"
},
"titleIgnorePrefix": {
"type": "string",
"description": "The title for sorting.",
"example": "First, The"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "The subtitle, if any.",
"example": "A Novel"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"description": "An id and a name.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its display name.",
"example": "Ann Author"
}
}
},
"description": "The authors."
},
"authorName": {
"type": "string",
"description": "The authors' names joined with `, `.",
"example": "Ann Author"
},
"authorNameLF": {
"type": "string",
"description": "The authors' names, family name first, joined with `, `.",
"example": "Author, Ann"
},
"narrators": {
"type": "array",
"items": {
"type": "string"
},
"description": "The narrators' names.",
"example": [
"Nia Narrator"
]
},
"narratorName": {
"type": "string",
"description": "The narrators' names joined with `, `.",
"example": "Nia Narrator"
},
"series": {
"type": "array",
"items": {
"type": "object",
"description": "A series an item belongs to, with the item's place in it.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The series name.",
"example": "Ann Author"
},
"sequence": {
"type": [
"string",
"null"
],
"description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
"example": "1"
}
}
},
"description": "The series the book is in."
},
"seriesName": {
"type": "string",
"description": "The series names with the book's place (`Name #2`), joined.",
"example": "The Saga #1"
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"description": "Genres.",
"example": [
"Fantasy"
]
},
"publishedYear": {
"type": [
"string",
"null"
],
"description": "The year of publication, as a string (`\"2019\"`).",
"example": "2024"
},
"publishedDate": {
"type": [
"string",
"null"
],
"description": "The date of publication, if known.",
"example": "2024-03-01"
},
"publisher": {
"type": [
"string",
"null"
],
"description": "The publisher.",
"example": "Example Press"
},
"description": {
"type": [
"string",
"null"
],
"description": "The description, as the library stores it.",
"example": "A short description."
},
"descriptionPlain": {
"type": [
"string",
"null"
],
"description": "The description with markup removed.",
"example": "A short description."
},
"isbn": {
"type": [
"string",
"null"
],
"description": "The ISBN, if known.",
"example": "9780000000002"
},
"asin": {
"type": [
"string",
"null"
],
"description": "The ASIN, if known.",
"example": "B000000000"
},
"language": {
"type": [
"string",
"null"
],
"description": "The language.",
"example": "en-us"
},
"explicit": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"abridged": {
"type": "boolean",
"description": "Whether the edition is abridged.",
"example": false
}
}
},
"coverPath": {
"type": [
"string",
"null"
],
"description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
"example": "/player/api/items/li_8f14e45fceea467f/cover"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags: none.",
"example": []
},
"numTracks": {
"type": "integer",
"format": "int64",
"description": "Tracks in play order.",
"example": 1,
"minimum": 0
},
"numAudioFiles": {
"type": "integer",
"format": "int64",
"description": "Audio files.",
"example": 1,
"minimum": 0
},
"numChapters": {
"type": "integer",
"format": "int64",
"description": "Chapters.",
"example": 0,
"minimum": 0
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds.",
"example": 36000.0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in its audio files.",
"example": 100000,
"minimum": 0
},
"audioFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "An audio file of a book.",
"required": [
"index",
"ino",
"metadata",
"addedAt",
"updatedAt",
"manuallyVerified",
"exclude",
"duration",
"chapters",
"metaTags",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The file's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"trackNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number the file's tags state: not read.",
"example": 1,
"minimum": 0
},
"discNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number the file's tags state: not read.",
"example": null,
"minimum": 0
},
"trackNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number in the file name: not read.",
"example": null,
"minimum": 0
},
"discNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number in the file name: not read.",
"example": null,
"minimum": 0
},
"manuallyVerified": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"exclude": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"error": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"format": {
"type": [
"string",
"null"
],
"description": "The container format, such as `mp4` or `mp3`.",
"example": "MP4A"
},
"duration": {
"type": "number",
"format": "double",
"description": "The file's length in seconds.",
"example": 36000.0
},
"bitRate": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Bits per second, if known.",
"example": 128000,
"minimum": 0
},
"language": {
"type": [
"string",
"null"
],
"description": "The file's language, if known.",
"example": "en-us"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"timeBase": {
"type": [
"string",
"null"
],
"description": "The time base, if known.",
"example": "1/44100"
},
"channels": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Audio channels, if known.",
"example": 2,
"minimum": 0
},
"channelLayout": {
"type": [
"string",
"null"
],
"description": "The channel layout, if known.",
"example": "stereo"
},
"chapters": {
"type": "array",
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "Chapters embedded in the file: none are read."
},
"embeddedCoverArt": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"metaTags": {
"type": "object",
"description": "Tags read from the file: none until the stored media probe reads\nthem."
},
"mimeType": {
"type": "string",
"description": "The file's media type, such as `audio/mp4`.",
"example": "audio/mp4"
}
}
},
"description": "The audio files, when fetched expanded."
},
"chapters": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "The chapters, when fetched expanded."
},
"tracks": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A track with its place in the book.",
"required": [
"index",
"startOffset",
"duration",
"title",
"contentUrl",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The track's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"startOffset": {
"type": "number",
"format": "double",
"description": "Where the track starts in the book, in seconds.",
"example": 0.0
},
"duration": {
"type": "number",
"format": "double",
"description": "The track's length in seconds.",
"example": 36000.0
},
"title": {
"type": "string",
"description": "The track's title: its file name.",
"example": "The First"
},
"contentUrl": {
"type": "string",
"description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
"example": "/player/api/items/li_8f14e45fceea467f/file/0"
},
"mimeType": {
"type": "string",
"description": "The track's media type.",
"example": "audio/mp4"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"metadata": {
"oneOf": [
{
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "The tracks with their place in the book, when fetched expanded."
}
}
},
"numFiles": {
"type": "integer",
"format": "int64",
"description": "Files in the item.",
"example": 1,
"minimum": 0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in all its files.",
"example": 100000,
"minimum": 0
},
"libraryFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A file of an item, in the expanded item's `libraryFiles`.",
"required": [
"ino",
"metadata",
"addedAt",
"updatedAt",
"fileType"
],
"properties": {
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"fileType": {
"type": "string",
"description": "Always `audio`.",
"example": "audio"
}
}
},
"description": "The item's files, when the item is fetched expanded."
},
"userMediaProgress": {
"oneOf": [
{
"type": "object",
"description": "The patron's progress, when the app asked for it.",
"required": [
"id",
"userId",
"libraryItemId",
"mediaItemId",
"mediaItemType",
"duration",
"progress",
"currentTime",
"isFinished",
"hideFromContinueListening",
"lastUpdate",
"startedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The progress id: the item id (one record per patron and item).",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaItemId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"mediaItemType": {
"type": "string",
"description": "Always `book`.",
"example": "book"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds, as last reported.",
"example": 36000.0
},
"progress": {
"type": "number",
"format": "double",
"description": "The share listened, from 0 to 1.",
"example": 0.05
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished it.",
"example": false
},
"hideFromContinueListening": {
"type": "boolean",
"description": "Whether it is hidden from continue listening.",
"example": false
},
"ebookLocation": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"ebookProgress": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Always null.",
"example": null
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When the progress last changed, in epoch milliseconds.",
"example": 1763630000000
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the patron started, in epoch milliseconds.",
"example": 1763620000000
},
"finishedAt": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron finished, in epoch milliseconds.",
"example": null
}
}
},
{
"type": "null"
}
]
},
"seriesSequence": {
"type": [
"string",
"null"
],
"description": "The item's place in a series, on a series' book list.",
"example": "1"
}
}
},
{
"type": "null"
}
]
}
}
}
Status 400: The body is malformed. As text/plain, when the body is not syntactically valid JSON.
Failed to parse the request body as JSON: expected value at line 1 column 1
Schema:
A text/plain body: a string.
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 404: No such item, or nothing of it this patron may play here.
Not Found
Schema:
A text/plain body: a string.
Status 413: The body is too long.
Payload Too Large
Schema:
A text/plain body: a string.
Status 415: The request did not declare a JSON body.
Expected request with `Content-Type: application/json`
Schema:
A text/plain body: a string.
Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.
Failed to deserialize the JSON body into the target type: mediaPlayer: invalid type: integer `1`, expected a string at line 1 column 16
Schema:
A text/plain body: a string.
Status 500: The library could not be read or written.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: Storage could not be asked; retry.
Service Unavailable
Schema:
A text/plain body: a string.
Streams one audio file of an item.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
idpathstringrequiredItem id.inopathstringrequiredThe file'sinofrom the item's tracks.Rangeheaderstring or nullOne byte range.
- 200The whole file. Body: binary (
audio/mp4) - 206The requested byte range. Body: binary (
audio/mp4) - 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 404No such item or file, or nothing of it this patron may play here. Body: string (
text/plain) -
416The range starts past the end of the file;
Content-Rangestates the size. Body:ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
- 500The library could not be read. Body: string (
text/plain) - 503Storage could not be asked; retry. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/items/<id>/file/<ino>' \
-H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/items/<id>/file/<ino>' `
-Headers @{ Authorization = 'Bearer <playerToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/player/api/items/<id>/file/<ino>",
headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/items/<id>/file/<ino>", {
headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/player/api/items/<id>/file/<ino>")
.header("Authorization", "Bearer <playerToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The whole file. The body is binary (audio/mp4).
Schema:
A audio/mp4 body: binary bytes.
Status 206: The requested byte range. The body is binary (audio/mp4).
Schema:
A audio/mp4 body: binary bytes.
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 404: No such item or file, or nothing of it this patron may play here.
Not Found
Schema:
A text/plain body: a string.
Status 416: The range starts past the end of the file; Content-Range states the size.
{
"error": "range_not_satisfiable"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 500: The library could not be read.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: Storage could not be asked; retry.
Service Unavailable
Schema:
A text/plain body: a string.
Downloads one audio file of an item for offline listening.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
idpathstringrequiredItem id.inopathstringrequiredThe file'sinofrom the item's audio files.Rangeheaderstring or nullOne byte range, to resume.
- 200The whole file, as an attachment. Body: binary (
audio/mp4) - 206The requested byte range. Body: binary (
audio/mp4) - 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron may not save files offline. Body: string (
text/plain) - 404No such item or file, or nothing of it this patron may play here. Body: string (
text/plain) -
416The range starts past the end of the file;
Content-Rangestates the size. Body:ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
- 500The library could not be read. Body: string (
text/plain) - 503Storage could not be asked; retry. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/items/<id>/file/<ino>/download' \
-H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/items/<id>/file/<ino>/download' `
-Headers @{ Authorization = 'Bearer <playerToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/player/api/items/<id>/file/<ino>/download",
headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/items/<id>/file/<ino>/download", {
headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/player/api/items/<id>/file/<ino>/download")
.header("Authorization", "Bearer <playerToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The whole file, as an attachment. The body is binary (audio/mp4).
Schema:
A audio/mp4 body: binary bytes.
Status 206: The requested byte range. The body is binary (audio/mp4).
Schema:
A audio/mp4 body: binary bytes.
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron may not save files offline.
Downloads are turned off for this patron
Schema:
A text/plain body: a string.
Status 404: No such item or file, or nothing of it this patron may play here.
Not Found
Schema:
A text/plain body: a string.
Status 416: The range starts past the end of the file; Content-Range states the size.
{
"error": "range_not_satisfiable"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 500: The library could not be read.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: Storage could not be asked; retry.
Service Unavailable
Schema:
A text/plain body: a string.
Reports where the patron is in a playing session.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
idpathstringrequiredSession id from the play answer.
Where the patron is, in seconds.
application/json: SyncBody
currentTimenumber (double) or nullThe position, in seconds.timeListenednumber (double) or nullSeconds listened since the last sync.durationnumber (double) or nullThe runtime the app measured, in seconds.
- 200
OK. Body: string (text/plain) - 400The body is malformed. As
text/plain, when the body is not syntactically valid JSON. Body: string (text/plain) - 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 404No such session of the patron's. Body: string (
text/plain) - 409The session ended; open a new one. Body: string (
text/plain) - 413The body is too long. Body: string (
text/plain) - 415The request did not declare a JSON body. Body: string (
text/plain) - 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (
text/plain) - 500The library could not be written. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/session/<id>/sync' \
-X POST \
-H 'Authorization: Bearer <playerToken>' \
-H 'Content-Type: application/json' \
-d '{}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/session/<id>/sync' `
-Method Post `
-Headers @{ Authorization = 'Bearer <playerToken>' } `
-ContentType 'application/json' `
-Body '{}'
import requests
response = requests.post(
"http://127.0.0.1:8787/player/api/session/<id>/sync",
headers={"Authorization": "Bearer <playerToken>"},
json={},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/session/<id>/sync", {
method: "POST",
headers: { Authorization: "Bearer <playerToken>", "Content-Type": "application/json" },
body: JSON.stringify({}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/player/api/session/<id>/sync")
.header("Authorization", "Bearer <playerToken>")
.json(&serde_json::json!({}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: OK.
string
Schema:
A text/plain body: a string.
Status 400: The body is malformed. As text/plain, when the body is not syntactically valid JSON.
Failed to parse the request body as JSON: expected value at line 1 column 1
Schema:
A text/plain body: a string.
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 404: No such session of the patron's.
Not Found
Schema:
A text/plain body: a string.
Status 409: The session ended; open a new one.
Session ended
Schema:
A text/plain body: a string.
Status 413: The body is too long.
Payload Too Large
Schema:
A text/plain body: a string.
Status 415: The request did not declare a JSON body.
Expected request with `Content-Type: application/json`
Schema:
A text/plain body: a string.
Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.
Failed to deserialize the JSON body into the target type: invalid type: null, expected struct SyncBody at line 1 column 4
Schema:
A text/plain body: a string.
Status 500: The library could not be written.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Sends a session's last report, if any, and ends it.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
idpathstringrequiredSession id from the play answer.
Optionally where the patron is, in seconds; empty keeps the last sync.
application/json: SyncBody
currentTimenumber (double) or nullThe position, in seconds.timeListenednumber (double) or nullSeconds listened since the last sync.durationnumber (double) or nullThe runtime the app measured, in seconds.
- 200
OK; the session is closed. Body: string (text/plain) - 400The body is malformed. As
text/plain, when the body is not syntactically valid JSON. Body: string (text/plain) - 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 404No such session of the patron's. Body: string (
text/plain) - 413The body is too long. Body: string (
text/plain) - 415The request did not declare a JSON body. Body: string (
text/plain) - 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (
text/plain) - 500The library could not be written. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/session/<id>/close' \
-X POST \
-H 'Authorization: Bearer <playerToken>' \
-H 'Content-Type: application/json' \
-d '{}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/session/<id>/close' `
-Method Post `
-Headers @{ Authorization = 'Bearer <playerToken>' } `
-ContentType 'application/json' `
-Body '{}'
import requests
response = requests.post(
"http://127.0.0.1:8787/player/api/session/<id>/close",
headers={"Authorization": "Bearer <playerToken>"},
json={},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/session/<id>/close", {
method: "POST",
headers: { Authorization: "Bearer <playerToken>", "Content-Type": "application/json" },
body: JSON.stringify({}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/player/api/session/<id>/close")
.header("Authorization", "Bearer <playerToken>")
.json(&serde_json::json!({}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: OK; the session is closed.
string
Schema:
A text/plain body: a string.
Status 400: The body is malformed. As text/plain, when the body is not syntactically valid JSON.
Failed to parse the request body as JSON: expected value at line 1 column 1
Schema:
A text/plain body: a string.
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 404: No such session of the patron's.
Not Found
Schema:
A text/plain body: a string.
Status 413: The body is too long.
Payload Too Large
Schema:
A text/plain body: a string.
Status 415: The request did not declare a JSON body.
Expected request with `Content-Type: application/json`
Schema:
A text/plain body: a string.
Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.
Failed to deserialize the JSON body into the target type: invalid type: null, expected struct SyncBody at line 1 column 4
Schema:
A text/plain body: a string.
Status 500: The library could not be written.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Uploads one session an app played offline.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
An offline session.
application/json: LocalSessionBody
idstringrequiredThe app's own id for the session.libraryItemIdstringrequiredThe item.currentTimenumber (double)requiredThe position, in seconds.timeListeningnumber (double) or nullSeconds listened in the session.durationnumber (double) or nullThe runtime the app measured, in seconds.updatedAtinteger (int64) or nullWhen the app last updated the session, in epoch milliseconds.
- 200
OK. Body: string (text/plain) - 400The body is malformed. As
text/plain, when the body is not syntactically valid JSON. Body: string (text/plain) - 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 404No such item. Body: string (
text/plain) - 413The body is too long. Body: string (
text/plain) - 415The request did not declare a JSON body. Body: string (
text/plain) - 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (
text/plain) - 500The library could not be written. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/session/local' \
-X POST \
-H 'Authorization: Bearer <playerToken>' \
-H 'Content-Type: application/json' \
-d '{"id": "6f9c1d2e-offline", "libraryItemId": "li_8f14e45fceea467f", "currentTime": 754.2}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/session/local' `
-Method Post `
-Headers @{ Authorization = 'Bearer <playerToken>' } `
-ContentType 'application/json' `
-Body '{"id": "6f9c1d2e-offline", "libraryItemId": "li_8f14e45fceea467f", "currentTime": 754.2}'
import requests
response = requests.post(
"http://127.0.0.1:8787/player/api/session/local",
headers={"Authorization": "Bearer <playerToken>"},
json={"id": "6f9c1d2e-offline", "libraryItemId": "li_8f14e45fceea467f", "currentTime": 754.2},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/session/local", {
method: "POST",
headers: { Authorization: "Bearer <playerToken>", "Content-Type": "application/json" },
body: JSON.stringify({"id": "6f9c1d2e-offline", "libraryItemId": "li_8f14e45fceea467f", "currentTime": 754.2}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/player/api/session/local")
.header("Authorization", "Bearer <playerToken>")
.json(&serde_json::json!({"id": "6f9c1d2e-offline", "libraryItemId": "li_8f14e45fceea467f", "currentTime": 754.2}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: OK.
string
Schema:
A text/plain body: a string.
Status 400: The body is malformed. As text/plain, when the body is not syntactically valid JSON.
Failed to parse the request body as JSON: expected value at line 1 column 1
Schema:
A text/plain body: a string.
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 404: No such item.
Not Found
Schema:
A text/plain body: a string.
Status 413: The body is too long.
Payload Too Large
Schema:
A text/plain body: a string.
Status 415: The request did not declare a JSON body.
Expected request with `Content-Type: application/json`
Schema:
A text/plain body: a string.
Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.
Failed to deserialize the JSON body into the target type: missing field `id` at line 1 column 2
Schema:
A text/plain body: a string.
Status 500: The library could not be written.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Uploads every session an app played offline.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
Offline sessions, each as POST /player/api/session/local takes one.
application/json: LocalSessionsBody
sessionsarray ofLocalSessionBodyrequiredThe sessions; each is answered on its own.
-
200Each session's outcome. Body:
SyncResults(application/json)1 fieldresultsarray ofSyncResultrequiredOne outcome per entry, in the order sent.
- 400The body is malformed. As
text/plain, when the body is not syntactically valid JSON. Body: string (text/plain) - 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 413The body is too long. Body: string (
text/plain) - 415The request did not declare a JSON body. Body: string (
text/plain) - 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/session/local-all' \
-X POST \
-H 'Authorization: Bearer <playerToken>' \
-H 'Content-Type: application/json' \
-d '{"sessions": [{"id": "6f9c1d2e-offline", "libraryItemId": "li_8f14e45fceea467f", "currentTime": 754.2}]}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/session/local-all' `
-Method Post `
-Headers @{ Authorization = 'Bearer <playerToken>' } `
-ContentType 'application/json' `
-Body '{"sessions": [{"id": "6f9c1d2e-offline", "libraryItemId": "li_8f14e45fceea467f", "currentTime": 754.2}]}'
import requests
response = requests.post(
"http://127.0.0.1:8787/player/api/session/local-all",
headers={"Authorization": "Bearer <playerToken>"},
json={"sessions": [{"id": "6f9c1d2e-offline", "libraryItemId": "li_8f14e45fceea467f", "currentTime": 754.2}]},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/session/local-all", {
method: "POST",
headers: { Authorization: "Bearer <playerToken>", "Content-Type": "application/json" },
body: JSON.stringify({"sessions": [{"id": "6f9c1d2e-offline", "libraryItemId": "li_8f14e45fceea467f", "currentTime": 754.2}]}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/player/api/session/local-all")
.header("Authorization", "Bearer <playerToken>")
.json(&serde_json::json!({"sessions": [{"id": "6f9c1d2e-offline", "libraryItemId": "li_8f14e45fceea467f", "currentTime": 754.2}]}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: Each session's outcome.
{
"results": [
{
"id": "li_8f14e45fceea467f",
"success": true,
"error": null
}
]
}
Schema:
{
"type": "object",
"description": "`POST /api/session/local-all`.",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"description": "One entry's outcome in a batch sync.",
"required": [
"id",
"success"
],
"properties": {
"id": {
"type": "string",
"description": "The session or item id the entry named.",
"example": "li_8f14e45fceea467f"
},
"success": {
"type": "boolean",
"description": "Whether it was applied.",
"example": true
},
"error": {
"type": [
"string",
"null"
],
"description": "Why not, when it was not.",
"example": null
}
}
},
"description": "One outcome per entry, in the order sent."
}
}
}
Status 400: The body is malformed. As text/plain, when the body is not syntactically valid JSON.
Failed to parse the request body as JSON: expected value at line 1 column 1
Schema:
A text/plain body: a string.
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 413: The body is too long.
Payload Too Large
Schema:
A text/plain body: a string.
Status 415: The request did not declare a JSON body.
Expected request with `Content-Type: application/json`
Schema:
A text/plain body: a string.
Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.
Failed to deserialize the JSON body into the target type: missing field `sessions` at line 1 column 2
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Reads the patron's progress on an item.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
idpathstringrequiredItem id.
-
200The progress. Body:
MediaProgress(application/json)16 fieldsidstringrequiredThe progress id: the item id (one record per patron and item).userIdstringrequiredThe patron's id.libraryItemIdstringrequiredThe item id.episodeIdstring or nullAlways null.mediaItemIdstringrequiredThe media id: the item id.mediaItemTypestringrequiredAlwaysbook.durationnumber (double)requiredThe book's length in seconds, as last reported.progressnumber (double)requiredThe share listened, from 0 to 1.currentTimenumber (double)requiredWhere the patron is, in seconds.isFinishedbooleanrequiredWhether the patron finished it.hideFromContinueListeningbooleanrequiredWhether it is hidden from continue listening.ebookLocationstring or nullAlways null.ebookProgressnumber (double) or nullAlways null.lastUpdateinteger (int64)requiredWhen the progress last changed, in epoch milliseconds.startedAtinteger (int64)requiredWhen the patron started, in epoch milliseconds.finishedAtinteger (int64) or nullWhen the patron finished, in epoch milliseconds.
- 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 404No progress on that item. Body: string (
text/plain) - 500The library could not be read. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/me/progress/<id>' \
-H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/me/progress/<id>' `
-Headers @{ Authorization = 'Bearer <playerToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/player/api/me/progress/<id>",
headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/me/progress/<id>", {
headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/player/api/me/progress/<id>")
.header("Authorization", "Bearer <playerToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The progress.
{
"id": "li_8f14e45fceea467f",
"userId": "42",
"libraryItemId": "li_8f14e45fceea467f",
"episodeId": null,
"mediaItemId": "li_8f14e45fceea467f",
"mediaItemType": "book",
"duration": 36000.0,
"progress": 0.05,
"currentTime": 1830.5,
"isFinished": false,
"hideFromContinueListening": false,
"ebookLocation": null,
"ebookProgress": null,
"lastUpdate": 1763630000000,
"startedAt": 1763620000000,
"finishedAt": null
}
Schema:
{
"type": "object",
"description": "The patron's progress on one item.",
"required": [
"id",
"userId",
"libraryItemId",
"mediaItemId",
"mediaItemType",
"duration",
"progress",
"currentTime",
"isFinished",
"hideFromContinueListening",
"lastUpdate",
"startedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The progress id: the item id (one record per patron and item).",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaItemId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"mediaItemType": {
"type": "string",
"description": "Always `book`.",
"example": "book"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds, as last reported.",
"example": 36000.0
},
"progress": {
"type": "number",
"format": "double",
"description": "The share listened, from 0 to 1.",
"example": 0.05
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished it.",
"example": false
},
"hideFromContinueListening": {
"type": "boolean",
"description": "Whether it is hidden from continue listening.",
"example": false
},
"ebookLocation": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"ebookProgress": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Always null.",
"example": null
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When the progress last changed, in epoch milliseconds.",
"example": 1763630000000
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the patron started, in epoch milliseconds.",
"example": 1763620000000
},
"finishedAt": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron finished, in epoch milliseconds.",
"example": null
}
}
}
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 404: No progress on that item.
Not Found
Schema:
A text/plain body: a string.
Status 500: The library could not be read.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Clears the patron's progress on an item.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
idpathstringrequiredItem id.
- 200
OK. Body: string (text/plain) - 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 404No such item. Body: string (
text/plain) - 500The library could not be written. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/me/progress/<id>' \
-X DELETE \
-H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/me/progress/<id>' `
-Method Delete `
-Headers @{ Authorization = 'Bearer <playerToken>' }
import requests
response = requests.delete(
"http://127.0.0.1:8787/player/api/me/progress/<id>",
headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/me/progress/<id>", {
method: "DELETE",
headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.delete("http://127.0.0.1:8787/player/api/me/progress/<id>")
.header("Authorization", "Bearer <playerToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: OK.
string
Schema:
A text/plain body: a string.
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 404: No such item.
Not Found
Schema:
A text/plain body: a string.
Status 500: The library could not be written.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Sets the patron's progress on an item: a seek, Mark finished or Start over.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
idpathstringrequiredItem id.
The fields to change.
application/json: ProgressBody
currentTimenumber (double) or nullThe position, in seconds.progressnumber (double) or nullThe share ofdurationlistened, 0 to 1, read whencurrentTimeis absent.durationnumber (double) or nullThe runtime, in seconds.isFinishedboolean or nullWhether the book is finished.hideFromContinueListeningboolean or nullTrue to take the item off Continue listening.
- 200
OK. Body: string (text/plain) - 400The body is malformed. As
text/plain, when the body is not syntactically valid JSON. Body: string (text/plain) - 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 404No such item. Body: string (
text/plain) - 413The body is too long. Body: string (
text/plain) - 415The request did not declare a JSON body. Body: string (
text/plain) - 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (
text/plain) - 500The library could not be written. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/me/progress/<id>' \
-X PATCH \
-H 'Authorization: Bearer <playerToken>' \
-H 'Content-Type: application/json' \
-d '{}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/me/progress/<id>' `
-Method Patch `
-Headers @{ Authorization = 'Bearer <playerToken>' } `
-ContentType 'application/json' `
-Body '{}'
import requests
response = requests.patch(
"http://127.0.0.1:8787/player/api/me/progress/<id>",
headers={"Authorization": "Bearer <playerToken>"},
json={},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/me/progress/<id>", {
method: "PATCH",
headers: { Authorization: "Bearer <playerToken>", "Content-Type": "application/json" },
body: JSON.stringify({}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.patch("http://127.0.0.1:8787/player/api/me/progress/<id>")
.header("Authorization", "Bearer <playerToken>")
.json(&serde_json::json!({}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: OK.
string
Schema:
A text/plain body: a string.
Status 400: The body is malformed. As text/plain, when the body is not syntactically valid JSON.
Failed to parse the request body as JSON: expected value at line 1 column 1
Schema:
A text/plain body: a string.
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 404: No such item.
Not Found
Schema:
A text/plain body: a string.
Status 413: The body is too long.
Payload Too Large
Schema:
A text/plain body: a string.
Status 415: The request did not declare a JSON body.
Expected request with `Content-Type: application/json`
Schema:
A text/plain body: a string.
Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.
Failed to deserialize the JSON body into the target type: isFinished: invalid type: integer `1`, expected a boolean at line 1 column 15
Schema:
A text/plain body: a string.
Status 500: The library could not be written.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Sets the patron's progress on several items.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
One change per item.
application/json: array of ProgressBatchEntry
- 200
OK. Body: string (text/plain) - 400The body is malformed. As
text/plain, when the body is not syntactically valid JSON. Body: string (text/plain) - 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 404An item is unknown. Body: string (
text/plain) - 413The body is too long. Body: string (
text/plain) - 415The request did not declare a JSON body. Body: string (
text/plain) - 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (
text/plain) - 500The library could not be written. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/me/progress/batch/update' \
-X PATCH \
-H 'Authorization: Bearer <playerToken>' \
-H 'Content-Type: application/json' \
-d '[{"libraryItemId": "li_8f14e45fceea467f"}]'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/me/progress/batch/update' `
-Method Patch `
-Headers @{ Authorization = 'Bearer <playerToken>' } `
-ContentType 'application/json' `
-Body '[{"libraryItemId": "li_8f14e45fceea467f"}]'
import requests
response = requests.patch(
"http://127.0.0.1:8787/player/api/me/progress/batch/update",
headers={"Authorization": "Bearer <playerToken>"},
json=[{"libraryItemId": "li_8f14e45fceea467f"}],
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/me/progress/batch/update", {
method: "PATCH",
headers: { Authorization: "Bearer <playerToken>", "Content-Type": "application/json" },
body: JSON.stringify([{"libraryItemId": "li_8f14e45fceea467f"}]),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.patch("http://127.0.0.1:8787/player/api/me/progress/batch/update")
.header("Authorization", "Bearer <playerToken>")
.json(&serde_json::json!([{"libraryItemId": "li_8f14e45fceea467f"}]))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: OK.
string
Schema:
A text/plain body: a string.
Status 400: The body is malformed. As text/plain, when the body is not syntactically valid JSON.
Failed to parse the request body as JSON: expected value at line 1 column 1
Schema:
A text/plain body: a string.
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 404: An item is unknown.
Not Found
Schema:
A text/plain body: a string.
Status 413: The body is too long.
Payload Too Large
Schema:
A text/plain body: a string.
Status 415: The request did not declare a JSON body.
Expected request with `Content-Type: application/json`
Schema:
A text/plain body: a string.
Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.
Failed to deserialize the JSON body into the target type: invalid type: null, expected a map at line 1 column 4
Schema:
A text/plain body: a string.
Status 500: The library could not be written.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Lists the items the patron is part way through, most recent first.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
-
200The items, each with the patron's progress. Body:
LibraryItems(application/json)1 fieldlibraryItemsarray ofLibraryItemrequiredThe items.
- 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 500The library could not be read. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/me/items-in-progress' \
-H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/me/items-in-progress' `
-Headers @{ Authorization = 'Bearer <playerToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/player/api/me/items-in-progress",
headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/me/items-in-progress", {
headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/player/api/me/items-in-progress")
.header("Authorization", "Bearer <playerToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The items, each with the patron's progress.
{
"libraryItems": [
{
"id": "li_8f14e45fceea467f",
"ino": "0",
"oldLibraryItemId": null,
"libraryId": "bookclerk-library",
"folderId": "bookclerk-library",
"path": "/the-first.m4b",
"relPath": "the-first.m4b",
"isFile": true,
"mtimeMs": 1763600000000,
"ctimeMs": 1763600000000,
"birthtimeMs": 1763600000000,
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"isMissing": false,
"isInvalid": false,
"mediaType": "book",
"media": {
"id": "li_8f14e45fceea467f",
"libraryItemId": "li_8f14e45fceea467f",
"metadata": {
"title": "The First",
"titleIgnorePrefix": "First, The",
"authors": [],
"authorName": "Ann Author",
"authorNameLF": "Author, Ann",
"narrators": [
"Nia Narrator"
],
"narratorName": "Nia Narrator",
"series": [],
"seriesName": "The Saga #1",
"genres": [
"Fantasy"
],
"explicit": false,
"abridged": false
},
"coverPath": "/player/api/items/li_8f14e45fceea467f/cover",
"tags": [],
"numTracks": 1,
"numAudioFiles": 1,
"numChapters": 0,
"duration": 36000.0,
"size": 100000,
"audioFiles": [],
"chapters": [],
"tracks": []
},
"numFiles": 1,
"size": 100000,
"libraryFiles": [
{
"ino": "0",
"metadata": {
"filename": "the-first.m4b",
"ext": ".m4b",
"path": "/the-first.m4b",
"relPath": "the-first.m4b",
"size": 100000,
"mtimeMs": 1763600000000,
"ctimeMs": 1763600000000,
"birthtimeMs": 1763600000000
},
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"fileType": "audio"
}
],
"userMediaProgress": {
"id": "li_8f14e45fceea467f",
"userId": "42",
"libraryItemId": "li_8f14e45fceea467f",
"episodeId": null,
"mediaItemId": "li_8f14e45fceea467f",
"mediaItemType": "book",
"duration": 36000.0,
"progress": 0.05,
"currentTime": 1830.5,
"isFinished": false,
"hideFromContinueListening": false,
"ebookLocation": null,
"ebookProgress": null,
"lastUpdate": 1763630000000,
"startedAt": 1763620000000,
"finishedAt": null
},
"seriesSequence": "1"
}
]
}
Schema:
{
"type": "object",
"description": "`{ \"libraryItems\": [...] }`: in-progress items and batch reads.",
"required": [
"libraryItems"
],
"properties": {
"libraryItems": {
"type": "array",
"items": {
"type": "object",
"description": "An item: an edition with a stored copy.",
"required": [
"id",
"ino",
"libraryId",
"folderId",
"path",
"relPath",
"isFile",
"mtimeMs",
"ctimeMs",
"birthtimeMs",
"addedAt",
"updatedAt",
"isMissing",
"isInvalid",
"mediaType",
"media",
"numFiles",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The item id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"ino": {
"type": "string",
"description": "The item's inode as apps expect one: the edition id again.",
"example": "0"
},
"oldLibraryItemId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"libraryId": {
"type": "string",
"description": "The library the item is listed in.",
"example": "bookclerk-library"
},
"folderId": {
"type": "string",
"description": "The folder id: the library id.",
"example": "bookclerk-library"
},
"path": {
"type": "string",
"description": "A display path: the title.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the title.",
"example": "the-first.m4b"
},
"isFile": {
"type": "boolean",
"description": "Always false: an item is a folder of tracks.",
"example": true
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy last changed, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the item joined the library, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When its record last changed, in epoch milliseconds.",
"example": 1763630000000
},
"isMissing": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"isInvalid": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"mediaType": {
"type": "string",
"description": "Always [`MEDIA_TYPE_BOOK`].",
"example": "book"
},
"media": {
"type": "object",
"description": "The book.",
"required": [
"id",
"metadata",
"tags",
"numTracks",
"numAudioFiles",
"numChapters",
"duration",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The media id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"libraryItemId": {
"type": [
"string",
"null"
],
"description": "The item id, when fetched expanded.",
"example": "li_8f14e45fceea467f"
},
"metadata": {
"type": "object",
"description": "The book's metadata.",
"required": [
"title",
"titleIgnorePrefix",
"authors",
"authorName",
"authorNameLF",
"narrators",
"narratorName",
"series",
"seriesName",
"genres",
"explicit",
"abridged"
],
"properties": {
"title": {
"type": "string",
"description": "The title.",
"example": "The First"
},
"titleIgnorePrefix": {
"type": "string",
"description": "The title for sorting.",
"example": "First, The"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "The subtitle, if any.",
"example": "A Novel"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"description": "An id and a name.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its display name.",
"example": "Ann Author"
}
}
},
"description": "The authors."
},
"authorName": {
"type": "string",
"description": "The authors' names joined with `, `.",
"example": "Ann Author"
},
"authorNameLF": {
"type": "string",
"description": "The authors' names, family name first, joined with `, `.",
"example": "Author, Ann"
},
"narrators": {
"type": "array",
"items": {
"type": "string"
},
"description": "The narrators' names.",
"example": [
"Nia Narrator"
]
},
"narratorName": {
"type": "string",
"description": "The narrators' names joined with `, `.",
"example": "Nia Narrator"
},
"series": {
"type": "array",
"items": {
"type": "object",
"description": "A series an item belongs to, with the item's place in it.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The series name.",
"example": "Ann Author"
},
"sequence": {
"type": [
"string",
"null"
],
"description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
"example": "1"
}
}
},
"description": "The series the book is in."
},
"seriesName": {
"type": "string",
"description": "The series names with the book's place (`Name #2`), joined.",
"example": "The Saga #1"
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"description": "Genres.",
"example": [
"Fantasy"
]
},
"publishedYear": {
"type": [
"string",
"null"
],
"description": "The year of publication, as a string (`\"2019\"`).",
"example": "2024"
},
"publishedDate": {
"type": [
"string",
"null"
],
"description": "The date of publication, if known.",
"example": "2024-03-01"
},
"publisher": {
"type": [
"string",
"null"
],
"description": "The publisher.",
"example": "Example Press"
},
"description": {
"type": [
"string",
"null"
],
"description": "The description, as the library stores it.",
"example": "A short description."
},
"descriptionPlain": {
"type": [
"string",
"null"
],
"description": "The description with markup removed.",
"example": "A short description."
},
"isbn": {
"type": [
"string",
"null"
],
"description": "The ISBN, if known.",
"example": "9780000000002"
},
"asin": {
"type": [
"string",
"null"
],
"description": "The ASIN, if known.",
"example": "B000000000"
},
"language": {
"type": [
"string",
"null"
],
"description": "The language.",
"example": "en-us"
},
"explicit": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"abridged": {
"type": "boolean",
"description": "Whether the edition is abridged.",
"example": false
}
}
},
"coverPath": {
"type": [
"string",
"null"
],
"description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
"example": "/player/api/items/li_8f14e45fceea467f/cover"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags: none.",
"example": []
},
"numTracks": {
"type": "integer",
"format": "int64",
"description": "Tracks in play order.",
"example": 1,
"minimum": 0
},
"numAudioFiles": {
"type": "integer",
"format": "int64",
"description": "Audio files.",
"example": 1,
"minimum": 0
},
"numChapters": {
"type": "integer",
"format": "int64",
"description": "Chapters.",
"example": 0,
"minimum": 0
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds.",
"example": 36000.0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in its audio files.",
"example": 100000,
"minimum": 0
},
"audioFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "An audio file of a book.",
"required": [
"index",
"ino",
"metadata",
"addedAt",
"updatedAt",
"manuallyVerified",
"exclude",
"duration",
"chapters",
"metaTags",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The file's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"trackNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number the file's tags state: not read.",
"example": 1,
"minimum": 0
},
"discNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number the file's tags state: not read.",
"example": null,
"minimum": 0
},
"trackNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number in the file name: not read.",
"example": null,
"minimum": 0
},
"discNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number in the file name: not read.",
"example": null,
"minimum": 0
},
"manuallyVerified": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"exclude": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"error": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"format": {
"type": [
"string",
"null"
],
"description": "The container format, such as `mp4` or `mp3`.",
"example": "MP4A"
},
"duration": {
"type": "number",
"format": "double",
"description": "The file's length in seconds.",
"example": 36000.0
},
"bitRate": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Bits per second, if known.",
"example": 128000,
"minimum": 0
},
"language": {
"type": [
"string",
"null"
],
"description": "The file's language, if known.",
"example": "en-us"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"timeBase": {
"type": [
"string",
"null"
],
"description": "The time base, if known.",
"example": "1/44100"
},
"channels": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Audio channels, if known.",
"example": 2,
"minimum": 0
},
"channelLayout": {
"type": [
"string",
"null"
],
"description": "The channel layout, if known.",
"example": "stereo"
},
"chapters": {
"type": "array",
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "Chapters embedded in the file: none are read."
},
"embeddedCoverArt": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"metaTags": {
"type": "object",
"description": "Tags read from the file: none until the stored media probe reads\nthem."
},
"mimeType": {
"type": "string",
"description": "The file's media type, such as `audio/mp4`.",
"example": "audio/mp4"
}
}
},
"description": "The audio files, when fetched expanded."
},
"chapters": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "The chapters, when fetched expanded."
},
"tracks": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A track with its place in the book.",
"required": [
"index",
"startOffset",
"duration",
"title",
"contentUrl",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The track's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"startOffset": {
"type": "number",
"format": "double",
"description": "Where the track starts in the book, in seconds.",
"example": 0.0
},
"duration": {
"type": "number",
"format": "double",
"description": "The track's length in seconds.",
"example": 36000.0
},
"title": {
"type": "string",
"description": "The track's title: its file name.",
"example": "The First"
},
"contentUrl": {
"type": "string",
"description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
"example": "/player/api/items/li_8f14e45fceea467f/file/0"
},
"mimeType": {
"type": "string",
"description": "The track's media type.",
"example": "audio/mp4"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"metadata": {
"oneOf": [
{
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "The tracks with their place in the book, when fetched expanded."
}
}
},
"numFiles": {
"type": "integer",
"format": "int64",
"description": "Files in the item.",
"example": 1,
"minimum": 0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in all its files.",
"example": 100000,
"minimum": 0
},
"libraryFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A file of an item, in the expanded item's `libraryFiles`.",
"required": [
"ino",
"metadata",
"addedAt",
"updatedAt",
"fileType"
],
"properties": {
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"fileType": {
"type": "string",
"description": "Always `audio`.",
"example": "audio"
}
}
},
"description": "The item's files, when the item is fetched expanded."
},
"userMediaProgress": {
"oneOf": [
{
"type": "object",
"description": "The patron's progress, when the app asked for it.",
"required": [
"id",
"userId",
"libraryItemId",
"mediaItemId",
"mediaItemType",
"duration",
"progress",
"currentTime",
"isFinished",
"hideFromContinueListening",
"lastUpdate",
"startedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The progress id: the item id (one record per patron and item).",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaItemId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"mediaItemType": {
"type": "string",
"description": "Always `book`.",
"example": "book"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds, as last reported.",
"example": 36000.0
},
"progress": {
"type": "number",
"format": "double",
"description": "The share listened, from 0 to 1.",
"example": 0.05
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished it.",
"example": false
},
"hideFromContinueListening": {
"type": "boolean",
"description": "Whether it is hidden from continue listening.",
"example": false
},
"ebookLocation": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"ebookProgress": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Always null.",
"example": null
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When the progress last changed, in epoch milliseconds.",
"example": 1763630000000
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the patron started, in epoch milliseconds.",
"example": 1763620000000
},
"finishedAt": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron finished, in epoch milliseconds.",
"example": null
}
}
},
{
"type": "null"
}
]
},
"seriesSequence": {
"type": [
"string",
"null"
],
"description": "The item's place in a series, on a series' book list.",
"example": "1"
}
}
},
"description": "The items."
}
}
}
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 500: The library could not be read.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Lists the patron's play sessions, newest first.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
itemsPerPagequeryinteger (int64)Sessions per page, default 10.pagequeryinteger (int64)Page number, from 0.
-
200A page of sessions. Body:
SessionPage(application/json)5 fieldstotalinteger (int64)requiredSessions in all. At least 0.numPagesinteger (int64)requiredPages in all. At least 0.pageinteger (int64)requiredThe page number, from 0. At least 0.itemsPerPageinteger (int64)requiredSessions per page. At least 0.sessionsarray ofPlaybackSessionrequiredThe page's sessions, newest first.
- 400A query value is out of range. Body: string (
text/plain) - 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 500The library could not be read. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/me/listening-sessions' \
-H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/me/listening-sessions' `
-Headers @{ Authorization = 'Bearer <playerToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/player/api/me/listening-sessions",
headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/me/listening-sessions", {
headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/player/api/me/listening-sessions")
.header("Authorization", "Bearer <playerToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: A page of sessions.
{
"total": 1,
"numPages": 1,
"page": 0,
"itemsPerPage": 20,
"sessions": [
{
"id": "li_8f14e45fceea467f",
"userId": "42",
"libraryId": "bookclerk-library",
"libraryItemId": "li_8f14e45fceea467f",
"bookId": "li_8f14e45fceea467f",
"episodeId": null,
"mediaType": "book",
"mediaMetadata": {
"title": "The First",
"titleIgnorePrefix": "First, The",
"subtitle": "A Novel",
"authors": [],
"authorName": "Ann Author",
"authorNameLF": "Author, Ann",
"narrators": [
"Nia Narrator"
],
"narratorName": "Nia Narrator",
"series": [],
"seriesName": "The Saga #1",
"genres": [
"Fantasy"
],
"publishedYear": "2024",
"publishedDate": "2024-03-01",
"publisher": "Example Press",
"description": "A short description.",
"descriptionPlain": "A short description.",
"isbn": "9780000000002",
"asin": "B000000000",
"language": "en-us",
"explicit": false,
"abridged": false
},
"chapters": [
{
"id": 1,
"start": 0.0,
"end": 600.0,
"title": "The First"
}
],
"displayTitle": "The First",
"displayAuthor": "Ann Author",
"coverPath": "/player/api/items/li_8f14e45fceea467f/cover",
"duration": 36000.0,
"playMethod": 1,
"mediaPlayer": "Absorb",
"deviceInfo": {
"deviceId": "pixel-8",
"deviceName": "Pixel 8",
"clientName": "Absorb"
},
"serverVersion": "2.17.0",
"date": "2026-11-20",
"dayOfWeek": "Friday",
"timeListening": 60.0,
"startTime": 1770.5,
"currentTime": 1830.5,
"startedAt": 1763620000000,
"updatedAt": 1763630000000,
"audioTracks": [
{
"index": 1,
"startOffset": 0.0,
"duration": 36000.0,
"title": "The First",
"contentUrl": "/player/api/items/li_8f14e45fceea467f/file/0",
"mimeType": "audio/mp4"
}
],
"libraryItem": {
"id": "li_8f14e45fceea467f",
"ino": "0",
"oldLibraryItemId": null,
"libraryId": "bookclerk-library",
"folderId": "bookclerk-library",
"path": "/the-first.m4b",
"relPath": "the-first.m4b",
"isFile": true,
"mtimeMs": 1763600000000,
"ctimeMs": 1763600000000,
"birthtimeMs": 1763600000000,
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"isMissing": false,
"isInvalid": false,
"mediaType": "book",
"media": {
"id": "li_8f14e45fceea467f",
"metadata": {
"title": "The First",
"titleIgnorePrefix": "First, The",
"authors": [],
"authorName": "Ann Author",
"authorNameLF": "Author, Ann",
"narrators": [
"Nia Narrator"
],
"narratorName": "Nia Narrator",
"series": [],
"seriesName": "The Saga #1",
"genres": [
"Fantasy"
],
"explicit": false,
"abridged": false
},
"tags": [],
"numTracks": 1,
"numAudioFiles": 1,
"numChapters": 0,
"duration": 36000.0,
"size": 100000
},
"numFiles": 1,
"size": 100000,
"libraryFiles": [],
"userMediaProgress": {
"id": "li_8f14e45fceea467f",
"userId": "42",
"libraryItemId": "li_8f14e45fceea467f",
"mediaItemId": "li_8f14e45fceea467f",
"mediaItemType": "book",
"duration": 36000.0,
"progress": 0.05,
"currentTime": 1830.5,
"isFinished": false,
"hideFromContinueListening": false,
"lastUpdate": 1763630000000,
"startedAt": 1763620000000
},
"seriesSequence": "1"
}
}
]
}
Schema:
{
"type": "object",
"description": "`GET /api/me/listening-sessions`.",
"required": [
"total",
"numPages",
"page",
"itemsPerPage",
"sessions"
],
"properties": {
"total": {
"type": "integer",
"format": "int64",
"description": "Sessions in all.",
"example": 1,
"minimum": 0
},
"numPages": {
"type": "integer",
"format": "int64",
"description": "Pages in all.",
"example": 1,
"minimum": 0
},
"page": {
"type": "integer",
"format": "int64",
"description": "The page number, from 0.",
"example": 0,
"minimum": 0
},
"itemsPerPage": {
"type": "integer",
"format": "int64",
"description": "Sessions per page.",
"example": 20,
"minimum": 0
},
"sessions": {
"type": "array",
"items": {
"type": "object",
"description": "A playback session, as `POST /api/items/{id}/play` answers.",
"required": [
"id",
"userId",
"libraryId",
"libraryItemId",
"bookId",
"mediaType",
"mediaMetadata",
"chapters",
"displayTitle",
"displayAuthor",
"duration",
"playMethod",
"mediaPlayer",
"deviceInfo",
"serverVersion",
"date",
"dayOfWeek",
"timeListening",
"startTime",
"currentTime",
"startedAt",
"updatedAt",
"audioTracks"
],
"properties": {
"id": {
"type": "string",
"description": "The session id; apps send it back to sync and close.",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryId": {
"type": "string",
"description": "The library id.",
"example": "bookclerk-library"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"bookId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaType": {
"type": "string",
"description": "Always [`MEDIA_TYPE_BOOK`].",
"example": "book"
},
"mediaMetadata": {
"type": "object",
"description": "The book's metadata.",
"required": [
"title",
"titleIgnorePrefix",
"authors",
"authorName",
"authorNameLF",
"narrators",
"narratorName",
"series",
"seriesName",
"genres",
"explicit",
"abridged"
],
"properties": {
"title": {
"type": "string",
"description": "The title.",
"example": "The First"
},
"titleIgnorePrefix": {
"type": "string",
"description": "The title for sorting.",
"example": "First, The"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "The subtitle, if any.",
"example": "A Novel"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"description": "An id and a name.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its display name.",
"example": "Ann Author"
}
}
},
"description": "The authors."
},
"authorName": {
"type": "string",
"description": "The authors' names joined with `, `.",
"example": "Ann Author"
},
"authorNameLF": {
"type": "string",
"description": "The authors' names, family name first, joined with `, `.",
"example": "Author, Ann"
},
"narrators": {
"type": "array",
"items": {
"type": "string"
},
"description": "The narrators' names.",
"example": [
"Nia Narrator"
]
},
"narratorName": {
"type": "string",
"description": "The narrators' names joined with `, `.",
"example": "Nia Narrator"
},
"series": {
"type": "array",
"items": {
"type": "object",
"description": "A series an item belongs to, with the item's place in it.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The series name.",
"example": "Ann Author"
},
"sequence": {
"type": [
"string",
"null"
],
"description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
"example": "1"
}
}
},
"description": "The series the book is in."
},
"seriesName": {
"type": "string",
"description": "The series names with the book's place (`Name #2`), joined.",
"example": "The Saga #1"
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"description": "Genres.",
"example": [
"Fantasy"
]
},
"publishedYear": {
"type": [
"string",
"null"
],
"description": "The year of publication, as a string (`\"2019\"`).",
"example": "2024"
},
"publishedDate": {
"type": [
"string",
"null"
],
"description": "The date of publication, if known.",
"example": "2024-03-01"
},
"publisher": {
"type": [
"string",
"null"
],
"description": "The publisher.",
"example": "Example Press"
},
"description": {
"type": [
"string",
"null"
],
"description": "The description, as the library stores it.",
"example": "A short description."
},
"descriptionPlain": {
"type": [
"string",
"null"
],
"description": "The description with markup removed.",
"example": "A short description."
},
"isbn": {
"type": [
"string",
"null"
],
"description": "The ISBN, if known.",
"example": "9780000000002"
},
"asin": {
"type": [
"string",
"null"
],
"description": "The ASIN, if known.",
"example": "B000000000"
},
"language": {
"type": [
"string",
"null"
],
"description": "The language.",
"example": "en-us"
},
"explicit": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"abridged": {
"type": "boolean",
"description": "Whether the edition is abridged.",
"example": false
}
}
},
"chapters": {
"type": "array",
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "The book's chapters."
},
"displayTitle": {
"type": "string",
"description": "The title apps show.",
"example": "The First"
},
"displayAuthor": {
"type": "string",
"description": "The author apps show.",
"example": "Ann Author"
},
"coverPath": {
"type": [
"string",
"null"
],
"description": "A cover path apps test for presence.",
"example": "/player/api/items/li_8f14e45fceea467f/cover"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds.",
"example": 36000.0
},
"playMethod": {
"type": "integer",
"format": "int32",
"description": "How the app plays: 0, direct play of the stored files.",
"example": 1,
"minimum": 0
},
"mediaPlayer": {
"type": "string",
"description": "The player the app reported.",
"example": "Absorb"
},
"deviceInfo": {
"type": "object",
"description": "The device the session was opened from.",
"required": [
"deviceId"
],
"properties": {
"deviceId": {
"type": "string",
"description": "The device's id: the card's session id.",
"example": "pixel-8"
},
"deviceName": {
"type": [
"string",
"null"
],
"description": "The device name the app reported, if any.",
"example": "Pixel 8"
},
"clientName": {
"type": [
"string",
"null"
],
"description": "The app's name, if reported.",
"example": "Absorb"
}
}
},
"serverVersion": {
"type": "string",
"description": "[`crate::COMPATIBLE_SERVER_VERSION`].",
"example": "2.17.0"
},
"date": {
"type": "string",
"description": "The day the session started, `YYYY-MM-DD` in UTC.",
"example": "2026-11-20"
},
"dayOfWeek": {
"type": "string",
"description": "The weekday the session started, in English.",
"example": "Friday"
},
"timeListening": {
"type": "number",
"format": "double",
"description": "Seconds listened in this session.",
"example": 60.0
},
"startTime": {
"type": "number",
"format": "double",
"description": "Where the session started, in seconds.",
"example": 1770.5
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the session started, in epoch milliseconds.",
"example": 1763620000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When it last synced, in epoch milliseconds.",
"example": 1763630000000
},
"audioTracks": {
"type": "array",
"items": {
"type": "object",
"description": "A track with its place in the book.",
"required": [
"index",
"startOffset",
"duration",
"title",
"contentUrl",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The track's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"startOffset": {
"type": "number",
"format": "double",
"description": "Where the track starts in the book, in seconds.",
"example": 0.0
},
"duration": {
"type": "number",
"format": "double",
"description": "The track's length in seconds.",
"example": 36000.0
},
"title": {
"type": "string",
"description": "The track's title: its file name.",
"example": "The First"
},
"contentUrl": {
"type": "string",
"description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
"example": "/player/api/items/li_8f14e45fceea467f/file/0"
},
"mimeType": {
"type": "string",
"description": "The track's media type.",
"example": "audio/mp4"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"metadata": {
"oneOf": [
{
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "The tracks to play, in order."
},
"libraryItem": {
"oneOf": [
{
"type": "object",
"description": "The item, expanded.",
"required": [
"id",
"ino",
"libraryId",
"folderId",
"path",
"relPath",
"isFile",
"mtimeMs",
"ctimeMs",
"birthtimeMs",
"addedAt",
"updatedAt",
"isMissing",
"isInvalid",
"mediaType",
"media",
"numFiles",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The item id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"ino": {
"type": "string",
"description": "The item's inode as apps expect one: the edition id again.",
"example": "0"
},
"oldLibraryItemId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"libraryId": {
"type": "string",
"description": "The library the item is listed in.",
"example": "bookclerk-library"
},
"folderId": {
"type": "string",
"description": "The folder id: the library id.",
"example": "bookclerk-library"
},
"path": {
"type": "string",
"description": "A display path: the title.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the title.",
"example": "the-first.m4b"
},
"isFile": {
"type": "boolean",
"description": "Always false: an item is a folder of tracks.",
"example": true
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy last changed, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the item joined the library, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When its record last changed, in epoch milliseconds.",
"example": 1763630000000
},
"isMissing": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"isInvalid": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"mediaType": {
"type": "string",
"description": "Always [`MEDIA_TYPE_BOOK`].",
"example": "book"
},
"media": {
"type": "object",
"description": "The book.",
"required": [
"id",
"metadata",
"tags",
"numTracks",
"numAudioFiles",
"numChapters",
"duration",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The media id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"libraryItemId": {
"type": [
"string",
"null"
],
"description": "The item id, when fetched expanded.",
"example": "li_8f14e45fceea467f"
},
"metadata": {
"type": "object",
"description": "The book's metadata.",
"required": [
"title",
"titleIgnorePrefix",
"authors",
"authorName",
"authorNameLF",
"narrators",
"narratorName",
"series",
"seriesName",
"genres",
"explicit",
"abridged"
],
"properties": {
"title": {
"type": "string",
"description": "The title.",
"example": "The First"
},
"titleIgnorePrefix": {
"type": "string",
"description": "The title for sorting.",
"example": "First, The"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "The subtitle, if any.",
"example": "A Novel"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"description": "An id and a name.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its display name.",
"example": "Ann Author"
}
}
},
"description": "The authors."
},
"authorName": {
"type": "string",
"description": "The authors' names joined with `, `.",
"example": "Ann Author"
},
"authorNameLF": {
"type": "string",
"description": "The authors' names, family name first, joined with `, `.",
"example": "Author, Ann"
},
"narrators": {
"type": "array",
"items": {
"type": "string"
},
"description": "The narrators' names.",
"example": [
"Nia Narrator"
]
},
"narratorName": {
"type": "string",
"description": "The narrators' names joined with `, `.",
"example": "Nia Narrator"
},
"series": {
"type": "array",
"items": {
"type": "object",
"description": "A series an item belongs to, with the item's place in it.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The series name.",
"example": "Ann Author"
},
"sequence": {
"type": [
"string",
"null"
],
"description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
"example": "1"
}
}
},
"description": "The series the book is in."
},
"seriesName": {
"type": "string",
"description": "The series names with the book's place (`Name #2`), joined.",
"example": "The Saga #1"
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"description": "Genres.",
"example": [
"Fantasy"
]
},
"publishedYear": {
"type": [
"string",
"null"
],
"description": "The year of publication, as a string (`\"2019\"`).",
"example": "2024"
},
"publishedDate": {
"type": [
"string",
"null"
],
"description": "The date of publication, if known.",
"example": "2024-03-01"
},
"publisher": {
"type": [
"string",
"null"
],
"description": "The publisher.",
"example": "Example Press"
},
"description": {
"type": [
"string",
"null"
],
"description": "The description, as the library stores it.",
"example": "A short description."
},
"descriptionPlain": {
"type": [
"string",
"null"
],
"description": "The description with markup removed.",
"example": "A short description."
},
"isbn": {
"type": [
"string",
"null"
],
"description": "The ISBN, if known.",
"example": "9780000000002"
},
"asin": {
"type": [
"string",
"null"
],
"description": "The ASIN, if known.",
"example": "B000000000"
},
"language": {
"type": [
"string",
"null"
],
"description": "The language.",
"example": "en-us"
},
"explicit": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"abridged": {
"type": "boolean",
"description": "Whether the edition is abridged.",
"example": false
}
}
},
"coverPath": {
"type": [
"string",
"null"
],
"description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
"example": "/player/api/items/li_8f14e45fceea467f/cover"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags: none.",
"example": []
},
"numTracks": {
"type": "integer",
"format": "int64",
"description": "Tracks in play order.",
"example": 1,
"minimum": 0
},
"numAudioFiles": {
"type": "integer",
"format": "int64",
"description": "Audio files.",
"example": 1,
"minimum": 0
},
"numChapters": {
"type": "integer",
"format": "int64",
"description": "Chapters.",
"example": 0,
"minimum": 0
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds.",
"example": 36000.0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in its audio files.",
"example": 100000,
"minimum": 0
},
"audioFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "An audio file of a book.",
"required": [
"index",
"ino",
"metadata",
"addedAt",
"updatedAt",
"manuallyVerified",
"exclude",
"duration",
"chapters",
"metaTags",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The file's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"trackNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number the file's tags state: not read.",
"example": 1,
"minimum": 0
},
"discNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number the file's tags state: not read.",
"example": null,
"minimum": 0
},
"trackNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number in the file name: not read.",
"example": null,
"minimum": 0
},
"discNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number in the file name: not read.",
"example": null,
"minimum": 0
},
"manuallyVerified": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"exclude": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"error": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"format": {
"type": [
"string",
"null"
],
"description": "The container format, such as `mp4` or `mp3`.",
"example": "MP4A"
},
"duration": {
"type": "number",
"format": "double",
"description": "The file's length in seconds.",
"example": 36000.0
},
"bitRate": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Bits per second, if known.",
"example": 128000,
"minimum": 0
},
"language": {
"type": [
"string",
"null"
],
"description": "The file's language, if known.",
"example": "en-us"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"timeBase": {
"type": [
"string",
"null"
],
"description": "The time base, if known.",
"example": "1/44100"
},
"channels": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Audio channels, if known.",
"example": 2,
"minimum": 0
},
"channelLayout": {
"type": [
"string",
"null"
],
"description": "The channel layout, if known.",
"example": "stereo"
},
"chapters": {
"type": "array",
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "Chapters embedded in the file: none are read."
},
"embeddedCoverArt": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"metaTags": {
"type": "object",
"description": "Tags read from the file: none until the stored media probe reads\nthem."
},
"mimeType": {
"type": "string",
"description": "The file's media type, such as `audio/mp4`.",
"example": "audio/mp4"
}
}
},
"description": "The audio files, when fetched expanded."
},
"chapters": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "The chapters, when fetched expanded."
},
"tracks": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A track with its place in the book.",
"required": [
"index",
"startOffset",
"duration",
"title",
"contentUrl",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The track's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"startOffset": {
"type": "number",
"format": "double",
"description": "Where the track starts in the book, in seconds.",
"example": 0.0
},
"duration": {
"type": "number",
"format": "double",
"description": "The track's length in seconds.",
"example": 36000.0
},
"title": {
"type": "string",
"description": "The track's title: its file name.",
"example": "The First"
},
"contentUrl": {
"type": "string",
"description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
"example": "/player/api/items/li_8f14e45fceea467f/file/0"
},
"mimeType": {
"type": "string",
"description": "The track's media type.",
"example": "audio/mp4"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"metadata": {
"oneOf": [
{
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "The tracks with their place in the book, when fetched expanded."
}
}
},
"numFiles": {
"type": "integer",
"format": "int64",
"description": "Files in the item.",
"example": 1,
"minimum": 0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in all its files.",
"example": 100000,
"minimum": 0
},
"libraryFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A file of an item, in the expanded item's `libraryFiles`.",
"required": [
"ino",
"metadata",
"addedAt",
"updatedAt",
"fileType"
],
"properties": {
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"fileType": {
"type": "string",
"description": "Always `audio`.",
"example": "audio"
}
}
},
"description": "The item's files, when the item is fetched expanded."
},
"userMediaProgress": {
"oneOf": [
{
"type": "object",
"description": "The patron's progress, when the app asked for it.",
"required": [
"id",
"userId",
"libraryItemId",
"mediaItemId",
"mediaItemType",
"duration",
"progress",
"currentTime",
"isFinished",
"hideFromContinueListening",
"lastUpdate",
"startedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The progress id: the item id (one record per patron and item).",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaItemId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"mediaItemType": {
"type": "string",
"description": "Always `book`.",
"example": "book"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds, as last reported.",
"example": 36000.0
},
"progress": {
"type": "number",
"format": "double",
"description": "The share listened, from 0 to 1.",
"example": 0.05
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished it.",
"example": false
},
"hideFromContinueListening": {
"type": "boolean",
"description": "Whether it is hidden from continue listening.",
"example": false
},
"ebookLocation": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"ebookProgress": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Always null.",
"example": null
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When the progress last changed, in epoch milliseconds.",
"example": 1763630000000
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the patron started, in epoch milliseconds.",
"example": 1763620000000
},
"finishedAt": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron finished, in epoch milliseconds.",
"example": null
}
}
},
{
"type": "null"
}
]
},
"seriesSequence": {
"type": [
"string",
"null"
],
"description": "The item's place in a series, on a series' book list.",
"example": "1"
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "The page's sessions, newest first."
}
}
}
Status 400: A query value is out of range.
Bad Request
Schema:
A text/plain body: a string.
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 500: The library could not be read.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Sums the patron's listening, by item and by day.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
-
200Listening totals over the patron's latest 1000 sessions. Body:
ListeningStats(application/json)6 fieldstotalTimenumber (double)requiredSeconds listened in all.itemsmap of string toItemListeningrequiredSeconds listened per item, by item id.daysmap of string to number (double)requiredSeconds listened per day, byYYYY-MM-DD.dayOfWeekmap of string to number (double)requiredSeconds listened per weekday, by English weekday name.todaynumber (double)requiredSeconds listened today.recentSessionsarray ofPlaybackSessionrequiredThe most recent sessions.
- 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 500The library could not be read. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/me/listening-stats' \
-H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/me/listening-stats' `
-Headers @{ Authorization = 'Bearer <playerToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/player/api/me/listening-stats",
headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/me/listening-stats", {
headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/player/api/me/listening-stats")
.header("Authorization", "Bearer <playerToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: Listening totals over the patron's latest 1000 sessions.
{
"totalTime": 7200.0,
"items": {},
"days": {
"2026-11-20": 1800.0
},
"dayOfWeek": {
"Friday": 1800.0
},
"today": 1800.0,
"recentSessions": [
{
"id": "li_8f14e45fceea467f",
"userId": "42",
"libraryId": "bookclerk-library",
"libraryItemId": "li_8f14e45fceea467f",
"bookId": "li_8f14e45fceea467f",
"episodeId": null,
"mediaType": "book",
"mediaMetadata": {
"title": "The First",
"titleIgnorePrefix": "First, The",
"subtitle": "A Novel",
"authors": [],
"authorName": "Ann Author",
"authorNameLF": "Author, Ann",
"narrators": [
"Nia Narrator"
],
"narratorName": "Nia Narrator",
"series": [],
"seriesName": "The Saga #1",
"genres": [
"Fantasy"
],
"publishedYear": "2024",
"publishedDate": "2024-03-01",
"publisher": "Example Press",
"description": "A short description.",
"descriptionPlain": "A short description.",
"isbn": "9780000000002",
"asin": "B000000000",
"language": "en-us",
"explicit": false,
"abridged": false
},
"chapters": [
{
"id": 1,
"start": 0.0,
"end": 600.0,
"title": "The First"
}
],
"displayTitle": "The First",
"displayAuthor": "Ann Author",
"coverPath": "/player/api/items/li_8f14e45fceea467f/cover",
"duration": 36000.0,
"playMethod": 1,
"mediaPlayer": "Absorb",
"deviceInfo": {
"deviceId": "pixel-8",
"deviceName": "Pixel 8",
"clientName": "Absorb"
},
"serverVersion": "2.17.0",
"date": "2026-11-20",
"dayOfWeek": "Friday",
"timeListening": 60.0,
"startTime": 1770.5,
"currentTime": 1830.5,
"startedAt": 1763620000000,
"updatedAt": 1763630000000,
"audioTracks": [
{
"index": 1,
"startOffset": 0.0,
"duration": 36000.0,
"title": "The First",
"contentUrl": "/player/api/items/li_8f14e45fceea467f/file/0",
"mimeType": "audio/mp4"
}
],
"libraryItem": {
"id": "li_8f14e45fceea467f",
"ino": "0",
"oldLibraryItemId": null,
"libraryId": "bookclerk-library",
"folderId": "bookclerk-library",
"path": "/the-first.m4b",
"relPath": "the-first.m4b",
"isFile": true,
"mtimeMs": 1763600000000,
"ctimeMs": 1763600000000,
"birthtimeMs": 1763600000000,
"addedAt": 1763600000000,
"updatedAt": 1763630000000,
"isMissing": false,
"isInvalid": false,
"mediaType": "book",
"media": {
"id": "li_8f14e45fceea467f",
"metadata": {
"title": "The First",
"titleIgnorePrefix": "First, The",
"authors": [],
"authorName": "Ann Author",
"authorNameLF": "Author, Ann",
"narrators": [
"Nia Narrator"
],
"narratorName": "Nia Narrator",
"series": [],
"seriesName": "The Saga #1",
"genres": [
"Fantasy"
],
"explicit": false,
"abridged": false
},
"tags": [],
"numTracks": 1,
"numAudioFiles": 1,
"numChapters": 0,
"duration": 36000.0,
"size": 100000
},
"numFiles": 1,
"size": 100000,
"libraryFiles": [],
"userMediaProgress": {
"id": "li_8f14e45fceea467f",
"userId": "42",
"libraryItemId": "li_8f14e45fceea467f",
"mediaItemId": "li_8f14e45fceea467f",
"mediaItemType": "book",
"duration": 36000.0,
"progress": 0.05,
"currentTime": 1830.5,
"isFinished": false,
"hideFromContinueListening": false,
"lastUpdate": 1763630000000,
"startedAt": 1763620000000
},
"seriesSequence": "1"
}
}
]
}
Schema:
{
"type": "object",
"description": "`GET /api/me/listening-stats`.",
"required": [
"totalTime",
"items",
"days",
"dayOfWeek",
"today",
"recentSessions"
],
"properties": {
"totalTime": {
"type": "number",
"format": "double",
"description": "Seconds listened in all.",
"example": 7200.0
},
"items": {
"type": "object",
"description": "Seconds listened per item, by item id.",
"additionalProperties": {
"type": "object",
"description": "Seconds listened to one item.",
"required": [
"id",
"timeListening",
"mediaMetadata"
],
"properties": {
"id": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"timeListening": {
"type": "number",
"format": "double",
"description": "Seconds listened.",
"example": 60.0
},
"mediaMetadata": {
"type": "object",
"description": "The item's metadata.",
"required": [
"title",
"titleIgnorePrefix",
"authors",
"authorName",
"authorNameLF",
"narrators",
"narratorName",
"series",
"seriesName",
"genres",
"explicit",
"abridged"
],
"properties": {
"title": {
"type": "string",
"description": "The title.",
"example": "The First"
},
"titleIgnorePrefix": {
"type": "string",
"description": "The title for sorting.",
"example": "First, The"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "The subtitle, if any.",
"example": "A Novel"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"description": "An id and a name.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its display name.",
"example": "Ann Author"
}
}
},
"description": "The authors."
},
"authorName": {
"type": "string",
"description": "The authors' names joined with `, `.",
"example": "Ann Author"
},
"authorNameLF": {
"type": "string",
"description": "The authors' names, family name first, joined with `, `.",
"example": "Author, Ann"
},
"narrators": {
"type": "array",
"items": {
"type": "string"
},
"description": "The narrators' names.",
"example": [
"Nia Narrator"
]
},
"narratorName": {
"type": "string",
"description": "The narrators' names joined with `, `.",
"example": "Nia Narrator"
},
"series": {
"type": "array",
"items": {
"type": "object",
"description": "A series an item belongs to, with the item's place in it.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The series name.",
"example": "Ann Author"
},
"sequence": {
"type": [
"string",
"null"
],
"description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
"example": "1"
}
}
},
"description": "The series the book is in."
},
"seriesName": {
"type": "string",
"description": "The series names with the book's place (`Name #2`), joined.",
"example": "The Saga #1"
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"description": "Genres.",
"example": [
"Fantasy"
]
},
"publishedYear": {
"type": [
"string",
"null"
],
"description": "The year of publication, as a string (`\"2019\"`).",
"example": "2024"
},
"publishedDate": {
"type": [
"string",
"null"
],
"description": "The date of publication, if known.",
"example": "2024-03-01"
},
"publisher": {
"type": [
"string",
"null"
],
"description": "The publisher.",
"example": "Example Press"
},
"description": {
"type": [
"string",
"null"
],
"description": "The description, as the library stores it.",
"example": "A short description."
},
"descriptionPlain": {
"type": [
"string",
"null"
],
"description": "The description with markup removed.",
"example": "A short description."
},
"isbn": {
"type": [
"string",
"null"
],
"description": "The ISBN, if known.",
"example": "9780000000002"
},
"asin": {
"type": [
"string",
"null"
],
"description": "The ASIN, if known.",
"example": "B000000000"
},
"language": {
"type": [
"string",
"null"
],
"description": "The language.",
"example": "en-us"
},
"explicit": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"abridged": {
"type": "boolean",
"description": "Whether the edition is abridged.",
"example": false
}
}
}
}
},
"propertyNames": {
"type": "string"
},
"example": {}
},
"days": {
"type": "object",
"description": "Seconds listened per day, by `YYYY-MM-DD`.",
"additionalProperties": {
"type": "number",
"format": "double"
},
"propertyNames": {
"type": "string"
},
"example": {
"2026-11-20": 1800.0
}
},
"dayOfWeek": {
"type": "object",
"description": "Seconds listened per weekday, by English weekday name.",
"additionalProperties": {
"type": "number",
"format": "double"
},
"propertyNames": {
"type": "string"
},
"example": {
"Friday": 1800.0
}
},
"today": {
"type": "number",
"format": "double",
"description": "Seconds listened today.",
"example": 1800.0
},
"recentSessions": {
"type": "array",
"items": {
"type": "object",
"description": "A playback session, as `POST /api/items/{id}/play` answers.",
"required": [
"id",
"userId",
"libraryId",
"libraryItemId",
"bookId",
"mediaType",
"mediaMetadata",
"chapters",
"displayTitle",
"displayAuthor",
"duration",
"playMethod",
"mediaPlayer",
"deviceInfo",
"serverVersion",
"date",
"dayOfWeek",
"timeListening",
"startTime",
"currentTime",
"startedAt",
"updatedAt",
"audioTracks"
],
"properties": {
"id": {
"type": "string",
"description": "The session id; apps send it back to sync and close.",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryId": {
"type": "string",
"description": "The library id.",
"example": "bookclerk-library"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"bookId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaType": {
"type": "string",
"description": "Always [`MEDIA_TYPE_BOOK`].",
"example": "book"
},
"mediaMetadata": {
"type": "object",
"description": "The book's metadata.",
"required": [
"title",
"titleIgnorePrefix",
"authors",
"authorName",
"authorNameLF",
"narrators",
"narratorName",
"series",
"seriesName",
"genres",
"explicit",
"abridged"
],
"properties": {
"title": {
"type": "string",
"description": "The title.",
"example": "The First"
},
"titleIgnorePrefix": {
"type": "string",
"description": "The title for sorting.",
"example": "First, The"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "The subtitle, if any.",
"example": "A Novel"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"description": "An id and a name.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its display name.",
"example": "Ann Author"
}
}
},
"description": "The authors."
},
"authorName": {
"type": "string",
"description": "The authors' names joined with `, `.",
"example": "Ann Author"
},
"authorNameLF": {
"type": "string",
"description": "The authors' names, family name first, joined with `, `.",
"example": "Author, Ann"
},
"narrators": {
"type": "array",
"items": {
"type": "string"
},
"description": "The narrators' names.",
"example": [
"Nia Narrator"
]
},
"narratorName": {
"type": "string",
"description": "The narrators' names joined with `, `.",
"example": "Nia Narrator"
},
"series": {
"type": "array",
"items": {
"type": "object",
"description": "A series an item belongs to, with the item's place in it.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The series name.",
"example": "Ann Author"
},
"sequence": {
"type": [
"string",
"null"
],
"description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
"example": "1"
}
}
},
"description": "The series the book is in."
},
"seriesName": {
"type": "string",
"description": "The series names with the book's place (`Name #2`), joined.",
"example": "The Saga #1"
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"description": "Genres.",
"example": [
"Fantasy"
]
},
"publishedYear": {
"type": [
"string",
"null"
],
"description": "The year of publication, as a string (`\"2019\"`).",
"example": "2024"
},
"publishedDate": {
"type": [
"string",
"null"
],
"description": "The date of publication, if known.",
"example": "2024-03-01"
},
"publisher": {
"type": [
"string",
"null"
],
"description": "The publisher.",
"example": "Example Press"
},
"description": {
"type": [
"string",
"null"
],
"description": "The description, as the library stores it.",
"example": "A short description."
},
"descriptionPlain": {
"type": [
"string",
"null"
],
"description": "The description with markup removed.",
"example": "A short description."
},
"isbn": {
"type": [
"string",
"null"
],
"description": "The ISBN, if known.",
"example": "9780000000002"
},
"asin": {
"type": [
"string",
"null"
],
"description": "The ASIN, if known.",
"example": "B000000000"
},
"language": {
"type": [
"string",
"null"
],
"description": "The language.",
"example": "en-us"
},
"explicit": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"abridged": {
"type": "boolean",
"description": "Whether the edition is abridged.",
"example": false
}
}
},
"chapters": {
"type": "array",
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "The book's chapters."
},
"displayTitle": {
"type": "string",
"description": "The title apps show.",
"example": "The First"
},
"displayAuthor": {
"type": "string",
"description": "The author apps show.",
"example": "Ann Author"
},
"coverPath": {
"type": [
"string",
"null"
],
"description": "A cover path apps test for presence.",
"example": "/player/api/items/li_8f14e45fceea467f/cover"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds.",
"example": 36000.0
},
"playMethod": {
"type": "integer",
"format": "int32",
"description": "How the app plays: 0, direct play of the stored files.",
"example": 1,
"minimum": 0
},
"mediaPlayer": {
"type": "string",
"description": "The player the app reported.",
"example": "Absorb"
},
"deviceInfo": {
"type": "object",
"description": "The device the session was opened from.",
"required": [
"deviceId"
],
"properties": {
"deviceId": {
"type": "string",
"description": "The device's id: the card's session id.",
"example": "pixel-8"
},
"deviceName": {
"type": [
"string",
"null"
],
"description": "The device name the app reported, if any.",
"example": "Pixel 8"
},
"clientName": {
"type": [
"string",
"null"
],
"description": "The app's name, if reported.",
"example": "Absorb"
}
}
},
"serverVersion": {
"type": "string",
"description": "[`crate::COMPATIBLE_SERVER_VERSION`].",
"example": "2.17.0"
},
"date": {
"type": "string",
"description": "The day the session started, `YYYY-MM-DD` in UTC.",
"example": "2026-11-20"
},
"dayOfWeek": {
"type": "string",
"description": "The weekday the session started, in English.",
"example": "Friday"
},
"timeListening": {
"type": "number",
"format": "double",
"description": "Seconds listened in this session.",
"example": 60.0
},
"startTime": {
"type": "number",
"format": "double",
"description": "Where the session started, in seconds.",
"example": 1770.5
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the session started, in epoch milliseconds.",
"example": 1763620000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When it last synced, in epoch milliseconds.",
"example": 1763630000000
},
"audioTracks": {
"type": "array",
"items": {
"type": "object",
"description": "A track with its place in the book.",
"required": [
"index",
"startOffset",
"duration",
"title",
"contentUrl",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The track's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"startOffset": {
"type": "number",
"format": "double",
"description": "Where the track starts in the book, in seconds.",
"example": 0.0
},
"duration": {
"type": "number",
"format": "double",
"description": "The track's length in seconds.",
"example": 36000.0
},
"title": {
"type": "string",
"description": "The track's title: its file name.",
"example": "The First"
},
"contentUrl": {
"type": "string",
"description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
"example": "/player/api/items/li_8f14e45fceea467f/file/0"
},
"mimeType": {
"type": "string",
"description": "The track's media type.",
"example": "audio/mp4"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"metadata": {
"oneOf": [
{
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "The tracks to play, in order."
},
"libraryItem": {
"oneOf": [
{
"type": "object",
"description": "The item, expanded.",
"required": [
"id",
"ino",
"libraryId",
"folderId",
"path",
"relPath",
"isFile",
"mtimeMs",
"ctimeMs",
"birthtimeMs",
"addedAt",
"updatedAt",
"isMissing",
"isInvalid",
"mediaType",
"media",
"numFiles",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The item id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"ino": {
"type": "string",
"description": "The item's inode as apps expect one: the edition id again.",
"example": "0"
},
"oldLibraryItemId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"libraryId": {
"type": "string",
"description": "The library the item is listed in.",
"example": "bookclerk-library"
},
"folderId": {
"type": "string",
"description": "The folder id: the library id.",
"example": "bookclerk-library"
},
"path": {
"type": "string",
"description": "A display path: the title.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the title.",
"example": "the-first.m4b"
},
"isFile": {
"type": "boolean",
"description": "Always false: an item is a folder of tracks.",
"example": true
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy last changed, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the copy was stored, in epoch milliseconds.",
"example": 1763600000000
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the item joined the library, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When its record last changed, in epoch milliseconds.",
"example": 1763630000000
},
"isMissing": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"isInvalid": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"mediaType": {
"type": "string",
"description": "Always [`MEDIA_TYPE_BOOK`].",
"example": "book"
},
"media": {
"type": "object",
"description": "The book.",
"required": [
"id",
"metadata",
"tags",
"numTracks",
"numAudioFiles",
"numChapters",
"duration",
"size"
],
"properties": {
"id": {
"type": "string",
"description": "The media id: the edition id.",
"example": "li_8f14e45fceea467f"
},
"libraryItemId": {
"type": [
"string",
"null"
],
"description": "The item id, when fetched expanded.",
"example": "li_8f14e45fceea467f"
},
"metadata": {
"type": "object",
"description": "The book's metadata.",
"required": [
"title",
"titleIgnorePrefix",
"authors",
"authorName",
"authorNameLF",
"narrators",
"narratorName",
"series",
"seriesName",
"genres",
"explicit",
"abridged"
],
"properties": {
"title": {
"type": "string",
"description": "The title.",
"example": "The First"
},
"titleIgnorePrefix": {
"type": "string",
"description": "The title for sorting.",
"example": "First, The"
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "The subtitle, if any.",
"example": "A Novel"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"description": "An id and a name.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "Its display name.",
"example": "Ann Author"
}
}
},
"description": "The authors."
},
"authorName": {
"type": "string",
"description": "The authors' names joined with `, `.",
"example": "Ann Author"
},
"authorNameLF": {
"type": "string",
"description": "The authors' names, family name first, joined with `, `.",
"example": "Author, Ann"
},
"narrators": {
"type": "array",
"items": {
"type": "string"
},
"description": "The narrators' names.",
"example": [
"Nia Narrator"
]
},
"narratorName": {
"type": "string",
"description": "The narrators' names joined with `, `.",
"example": "Nia Narrator"
},
"series": {
"type": "array",
"items": {
"type": "object",
"description": "A series an item belongs to, with the item's place in it.",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The series id.",
"example": "li_8f14e45fceea467f"
},
"name": {
"type": "string",
"description": "The series name.",
"example": "Ann Author"
},
"sequence": {
"type": [
"string",
"null"
],
"description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
"example": "1"
}
}
},
"description": "The series the book is in."
},
"seriesName": {
"type": "string",
"description": "The series names with the book's place (`Name #2`), joined.",
"example": "The Saga #1"
},
"genres": {
"type": "array",
"items": {
"type": "string"
},
"description": "Genres.",
"example": [
"Fantasy"
]
},
"publishedYear": {
"type": [
"string",
"null"
],
"description": "The year of publication, as a string (`\"2019\"`).",
"example": "2024"
},
"publishedDate": {
"type": [
"string",
"null"
],
"description": "The date of publication, if known.",
"example": "2024-03-01"
},
"publisher": {
"type": [
"string",
"null"
],
"description": "The publisher.",
"example": "Example Press"
},
"description": {
"type": [
"string",
"null"
],
"description": "The description, as the library stores it.",
"example": "A short description."
},
"descriptionPlain": {
"type": [
"string",
"null"
],
"description": "The description with markup removed.",
"example": "A short description."
},
"isbn": {
"type": [
"string",
"null"
],
"description": "The ISBN, if known.",
"example": "9780000000002"
},
"asin": {
"type": [
"string",
"null"
],
"description": "The ASIN, if known.",
"example": "B000000000"
},
"language": {
"type": [
"string",
"null"
],
"description": "The language.",
"example": "en-us"
},
"explicit": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"abridged": {
"type": "boolean",
"description": "Whether the edition is abridged.",
"example": false
}
}
},
"coverPath": {
"type": [
"string",
"null"
],
"description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
"example": "/player/api/items/li_8f14e45fceea467f/cover"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags: none.",
"example": []
},
"numTracks": {
"type": "integer",
"format": "int64",
"description": "Tracks in play order.",
"example": 1,
"minimum": 0
},
"numAudioFiles": {
"type": "integer",
"format": "int64",
"description": "Audio files.",
"example": 1,
"minimum": 0
},
"numChapters": {
"type": "integer",
"format": "int64",
"description": "Chapters.",
"example": 0,
"minimum": 0
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds.",
"example": 36000.0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in its audio files.",
"example": 100000,
"minimum": 0
},
"audioFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "An audio file of a book.",
"required": [
"index",
"ino",
"metadata",
"addedAt",
"updatedAt",
"manuallyVerified",
"exclude",
"duration",
"chapters",
"metaTags",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The file's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"trackNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number the file's tags state: not read.",
"example": 1,
"minimum": 0
},
"discNumFromMeta": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number the file's tags state: not read.",
"example": null,
"minimum": 0
},
"trackNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The track number in the file name: not read.",
"example": null,
"minimum": 0
},
"discNumFromFilename": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The disc number in the file name: not read.",
"example": null,
"minimum": 0
},
"manuallyVerified": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"exclude": {
"type": "boolean",
"description": "Always false.",
"example": false
},
"error": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"format": {
"type": [
"string",
"null"
],
"description": "The container format, such as `mp4` or `mp3`.",
"example": "MP4A"
},
"duration": {
"type": "number",
"format": "double",
"description": "The file's length in seconds.",
"example": 36000.0
},
"bitRate": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Bits per second, if known.",
"example": 128000,
"minimum": 0
},
"language": {
"type": [
"string",
"null"
],
"description": "The file's language, if known.",
"example": "en-us"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"timeBase": {
"type": [
"string",
"null"
],
"description": "The time base, if known.",
"example": "1/44100"
},
"channels": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Audio channels, if known.",
"example": 2,
"minimum": 0
},
"channelLayout": {
"type": [
"string",
"null"
],
"description": "The channel layout, if known.",
"example": "stereo"
},
"chapters": {
"type": "array",
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "Chapters embedded in the file: none are read."
},
"embeddedCoverArt": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"metaTags": {
"type": "object",
"description": "Tags read from the file: none until the stored media probe reads\nthem."
},
"mimeType": {
"type": "string",
"description": "The file's media type, such as `audio/mp4`.",
"example": "audio/mp4"
}
}
},
"description": "The audio files, when fetched expanded."
},
"chapters": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A chapter of a book.",
"required": [
"id",
"start",
"end",
"title"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "The chapter's place, from 0.",
"example": 1,
"minimum": 0
},
"start": {
"type": "number",
"format": "double",
"description": "Where it starts, in seconds.",
"example": 0.0
},
"end": {
"type": "number",
"format": "double",
"description": "Where it ends, in seconds.",
"example": 600.0
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
}
}
},
"description": "The chapters, when fetched expanded."
},
"tracks": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A track with its place in the book.",
"required": [
"index",
"startOffset",
"duration",
"title",
"contentUrl",
"mimeType"
],
"properties": {
"index": {
"type": "integer",
"format": "int64",
"description": "The track's place in play order, from 1.",
"example": 1,
"minimum": 0
},
"startOffset": {
"type": "number",
"format": "double",
"description": "Where the track starts in the book, in seconds.",
"example": 0.0
},
"duration": {
"type": "number",
"format": "double",
"description": "The track's length in seconds.",
"example": 36000.0
},
"title": {
"type": "string",
"description": "The track's title: its file name.",
"example": "The First"
},
"contentUrl": {
"type": "string",
"description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
"example": "/player/api/items/li_8f14e45fceea467f/file/0"
},
"mimeType": {
"type": "string",
"description": "The track's media type.",
"example": "audio/mp4"
},
"codec": {
"type": [
"string",
"null"
],
"description": "The codec, if known.",
"example": "aac"
},
"metadata": {
"oneOf": [
{
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "The tracks with their place in the book, when fetched expanded."
}
}
},
"numFiles": {
"type": "integer",
"format": "int64",
"description": "Files in the item.",
"example": 1,
"minimum": 0
},
"size": {
"type": "integer",
"format": "int64",
"description": "Bytes in all its files.",
"example": 100000,
"minimum": 0
},
"libraryFiles": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "A file of an item, in the expanded item's `libraryFiles`.",
"required": [
"ino",
"metadata",
"addedAt",
"updatedAt",
"fileType"
],
"properties": {
"ino": {
"type": "string",
"description": "The file's `ino` ([`crate::ids::file_ino`]).",
"example": "0"
},
"metadata": {
"type": "object",
"description": "The file's name, size and times.",
"required": [
"filename",
"ext",
"path",
"relPath",
"size",
"mtimeMs",
"ctimeMs",
"birthtimeMs"
],
"properties": {
"filename": {
"type": "string",
"description": "The file name.",
"example": "the-first.m4b"
},
"ext": {
"type": "string",
"description": "The extension with its dot (`.m4b`).",
"example": ".m4b"
},
"path": {
"type": "string",
"description": "A display path: the file name.",
"example": "/the-first.m4b"
},
"relPath": {
"type": "string",
"description": "A display path: the file name.",
"example": "the-first.m4b"
},
"size": {
"type": "integer",
"format": "int64",
"description": "The file's size in bytes.",
"example": 100000,
"minimum": 0
},
"mtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"ctimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"birthtimeMs": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
}
}
},
"addedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763600000000
},
"updatedAt": {
"type": "integer",
"format": "int64",
"description": "When the file was stored, in epoch milliseconds.",
"example": 1763630000000
},
"fileType": {
"type": "string",
"description": "Always `audio`.",
"example": "audio"
}
}
},
"description": "The item's files, when the item is fetched expanded."
},
"userMediaProgress": {
"oneOf": [
{
"type": "object",
"description": "The patron's progress, when the app asked for it.",
"required": [
"id",
"userId",
"libraryItemId",
"mediaItemId",
"mediaItemType",
"duration",
"progress",
"currentTime",
"isFinished",
"hideFromContinueListening",
"lastUpdate",
"startedAt"
],
"properties": {
"id": {
"type": "string",
"description": "The progress id: the item id (one record per patron and item).",
"example": "li_8f14e45fceea467f"
},
"userId": {
"type": "string",
"description": "The patron's id.",
"example": "42"
},
"libraryItemId": {
"type": "string",
"description": "The item id.",
"example": "li_8f14e45fceea467f"
},
"episodeId": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"mediaItemId": {
"type": "string",
"description": "The media id: the item id.",
"example": "li_8f14e45fceea467f"
},
"mediaItemType": {
"type": "string",
"description": "Always `book`.",
"example": "book"
},
"duration": {
"type": "number",
"format": "double",
"description": "The book's length in seconds, as last reported.",
"example": 36000.0
},
"progress": {
"type": "number",
"format": "double",
"description": "The share listened, from 0 to 1.",
"example": 0.05
},
"currentTime": {
"type": "number",
"format": "double",
"description": "Where the patron is, in seconds.",
"example": 1830.5
},
"isFinished": {
"type": "boolean",
"description": "Whether the patron finished it.",
"example": false
},
"hideFromContinueListening": {
"type": "boolean",
"description": "Whether it is hidden from continue listening.",
"example": false
},
"ebookLocation": {
"type": [
"string",
"null"
],
"description": "Always null.",
"example": null
},
"ebookProgress": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Always null.",
"example": null
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "When the progress last changed, in epoch milliseconds.",
"example": 1763630000000
},
"startedAt": {
"type": "integer",
"format": "int64",
"description": "When the patron started, in epoch milliseconds.",
"example": 1763620000000
},
"finishedAt": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the patron finished, in epoch milliseconds.",
"example": null
}
}
},
{
"type": "null"
}
]
},
"seriesSequence": {
"type": [
"string",
"null"
],
"description": "The item's place in a series, on a series' book list.",
"example": "1"
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "The most recent sessions."
}
}
}
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 500: The library could not be read.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Adds a bookmark to an item.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
idpathstringrequiredItem id.
The place, in seconds, and a title.
application/json: BookmarkBody
timenumber (double)requiredThe place, in seconds; onPATCH, which bookmark to rename.titlestring or nullThe bookmark's title.
-
200The bookmark. Body:
Bookmark(application/json)4 fieldslibraryItemIdstringrequiredThe item it is in.titlestringrequiredIts title.timenumber (double)requiredWhere it is, in seconds.createdAtinteger (int64)requiredWhen it was made, in epoch milliseconds.
- 400The body is malformed. As
text/plain, when the body is not syntactically valid JSON. Body: string (text/plain) - 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 404No such item. Body: string (
text/plain) - 409The patron has as many bookmarks as the library keeps. Body: string (
text/plain) - 413The body is too long. Body: string (
text/plain) - 415The request did not declare a JSON body. Body: string (
text/plain) - 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (
text/plain) - 500The library could not be written. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/me/item/<id>/bookmark' \
-X POST \
-H 'Authorization: Bearer <playerToken>' \
-H 'Content-Type: application/json' \
-d '{"time": 1830.0}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/me/item/<id>/bookmark' `
-Method Post `
-Headers @{ Authorization = 'Bearer <playerToken>' } `
-ContentType 'application/json' `
-Body '{"time": 1830.0}'
import requests
response = requests.post(
"http://127.0.0.1:8787/player/api/me/item/<id>/bookmark",
headers={"Authorization": "Bearer <playerToken>"},
json={"time": 1830.0},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/me/item/<id>/bookmark", {
method: "POST",
headers: { Authorization: "Bearer <playerToken>", "Content-Type": "application/json" },
body: JSON.stringify({"time": 1830.0}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/player/api/me/item/<id>/bookmark")
.header("Authorization", "Bearer <playerToken>")
.json(&serde_json::json!({"time": 1830.0}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The bookmark.
{
"libraryItemId": "li_8f14e45fceea467f",
"title": "The First",
"time": 1830.0,
"createdAt": 1763600000000
}
Schema:
{
"type": "object",
"description": "A bookmark.",
"required": [
"libraryItemId",
"title",
"time",
"createdAt"
],
"properties": {
"libraryItemId": {
"type": "string",
"description": "The item it is in.",
"example": "li_8f14e45fceea467f"
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
},
"time": {
"type": "number",
"format": "double",
"description": "Where it is, in seconds.",
"example": 1830.0
},
"createdAt": {
"type": "integer",
"format": "int64",
"description": "When it was made, in epoch milliseconds.",
"example": 1763600000000
}
}
}
Status 400: The body is malformed. As text/plain, when the body is not syntactically valid JSON.
Failed to parse the request body as JSON: expected value at line 1 column 1
Schema:
A text/plain body: a string.
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 404: No such item.
Not Found
Schema:
A text/plain body: a string.
Status 409: The patron has as many bookmarks as the library keeps.
Too many bookmarks
Schema:
A text/plain body: a string.
Status 413: The body is too long.
Payload Too Large
Schema:
A text/plain body: a string.
Status 415: The request did not declare a JSON body.
Expected request with `Content-Type: application/json`
Schema:
A text/plain body: a string.
Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.
Failed to deserialize the JSON body into the target type: missing field `time` at line 1 column 2
Schema:
A text/plain body: a string.
Status 500: The library could not be written.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Renames the bookmark at a time in an item.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
idpathstringrequiredItem id.
Which bookmark, by its place in seconds, and its new title.
application/json: BookmarkBody
timenumber (double)requiredThe place, in seconds; onPATCH, which bookmark to rename.titlestring or nullThe bookmark's title.
-
200The bookmark. Body:
Bookmark(application/json)4 fieldslibraryItemIdstringrequiredThe item it is in.titlestringrequiredIts title.timenumber (double)requiredWhere it is, in seconds.createdAtinteger (int64)requiredWhen it was made, in epoch milliseconds.
- 400The body is malformed. As
text/plain, when the body is not syntactically valid JSON. Body: string (text/plain) - 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 404No such item or bookmark. Body: string (
text/plain) - 413The body is too long. Body: string (
text/plain) - 415The request did not declare a JSON body. Body: string (
text/plain) - 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (
text/plain) - 500The library could not be written. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/me/item/<id>/bookmark' \
-X PATCH \
-H 'Authorization: Bearer <playerToken>' \
-H 'Content-Type: application/json' \
-d '{"time": 1830.0}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/me/item/<id>/bookmark' `
-Method Patch `
-Headers @{ Authorization = 'Bearer <playerToken>' } `
-ContentType 'application/json' `
-Body '{"time": 1830.0}'
import requests
response = requests.patch(
"http://127.0.0.1:8787/player/api/me/item/<id>/bookmark",
headers={"Authorization": "Bearer <playerToken>"},
json={"time": 1830.0},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/me/item/<id>/bookmark", {
method: "PATCH",
headers: { Authorization: "Bearer <playerToken>", "Content-Type": "application/json" },
body: JSON.stringify({"time": 1830.0}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.patch("http://127.0.0.1:8787/player/api/me/item/<id>/bookmark")
.header("Authorization", "Bearer <playerToken>")
.json(&serde_json::json!({"time": 1830.0}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The bookmark.
{
"libraryItemId": "li_8f14e45fceea467f",
"title": "The First",
"time": 1830.0,
"createdAt": 1763600000000
}
Schema:
{
"type": "object",
"description": "A bookmark.",
"required": [
"libraryItemId",
"title",
"time",
"createdAt"
],
"properties": {
"libraryItemId": {
"type": "string",
"description": "The item it is in.",
"example": "li_8f14e45fceea467f"
},
"title": {
"type": "string",
"description": "Its title.",
"example": "The First"
},
"time": {
"type": "number",
"format": "double",
"description": "Where it is, in seconds.",
"example": 1830.0
},
"createdAt": {
"type": "integer",
"format": "int64",
"description": "When it was made, in epoch milliseconds.",
"example": 1763600000000
}
}
}
Status 400: The body is malformed. As text/plain, when the body is not syntactically valid JSON.
Failed to parse the request body as JSON: expected value at line 1 column 1
Schema:
A text/plain body: a string.
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 404: No such item or bookmark.
Not Found
Schema:
A text/plain body: a string.
Status 413: The body is too long.
Payload Too Large
Schema:
A text/plain body: a string.
Status 415: The request did not declare a JSON body.
Expected request with `Content-Type: application/json`
Schema:
A text/plain body: a string.
Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.
Failed to deserialize the JSON body into the target type: missing field `time` at line 1 column 2
Schema:
A text/plain body: a string.
Status 500: The library could not be written.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Removes the bookmark at a time in an item.
Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.
Credentials: playerToken
idpathstringrequiredItem id.timepathstringrequiredThe bookmark's time in seconds.
- 200
OK. Body: string (text/plain) - 401No live player card (
Unauthorized, plain text). Body: string (text/plain) - 403The patron must enroll a second factor on the library's website first (plain text). Body: string (
text/plain) - 404No such item or bookmark. Body: string (
text/plain) - 500The library could not be written. Body: string (
text/plain) - 503The card could not be checked; retry (plain text). Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/player/api/me/item/<id>/bookmark/<time>' \
-X DELETE \
-H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/me/item/<id>/bookmark/<time>' `
-Method Delete `
-Headers @{ Authorization = 'Bearer <playerToken>' }
import requests
response = requests.delete(
"http://127.0.0.1:8787/player/api/me/item/<id>/bookmark/<time>",
headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/me/item/<id>/bookmark/<time>", {
method: "DELETE",
headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.delete("http://127.0.0.1:8787/player/api/me/item/<id>/bookmark/<time>")
.header("Authorization", "Bearer <playerToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: OK.
string
Schema:
A text/plain body: a string.
Status 401: No live player card (Unauthorized, plain text).
Unauthorized
Schema:
A text/plain body: a string.
Status 403: The patron must enroll a second factor on the library's website first (plain text).
Enroll a second factor on the library's website first
Schema:
A text/plain body: a string.
Status 404: No such item or bookmark.
Not Found
Schema:
A text/plain body: a string.
Status 500: The library could not be written.
Internal Server Error
Schema:
A text/plain body: a string.
Status 503: The card could not be checked; retry (plain text).
Service Unavailable
Schema:
A text/plain body: a string.
Generated from crates/bookclerkd/openapi.json at main · View as Markdown