groove/audiobookshelf
1
0
Fork 0
mirror of https://github.com/advplyr/audiobookshelf.git synced 2026-07-11 03:41:42 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4
audiobookshelf/docs/bundled.yaml

4036 lines
264 KiB
YAML
Raw Blame History

openapi: 3.0.0
info:
title: Audiobookshelf API
version: 0.1.0
description: Audiobookshelf API with autogenerated OpenAPI doc
servers:
- url: http://localhost:3000
description: Development server
security:
- BearerAuth: []
tags:
- name: Authors
description: Author endpoints
- name: Libraries
description: Library endpoints
- name: Series
description: Series endpoints
- name: Email
description: Email endpoints
- name: Notification
description: Notifications endpoints
- name: Podcasts
description: Podcast endpoints
- name: Auth
description: Authentication endpoints
- name: Me
description: User endpoints
- name: Session
description: Session endpoints
paths:
/api/authors/{id}:
parameters:
- name: id
in: path
description: Author ID
required: true
schema:
$ref: '#/components/schemas/authorId'
get:
operationId: getAuthorById
summary: Get an author by ID
description: Get an author by ID. The author's books and series can be included in the response.
tags:
- Authors
parameters:
- in: query
name: include
description: A comma separated list of what to include with the author. The options are `items` and `series`. `series` will only have an effect if `items` is included. For example, the value `items,series` will include both library items and series.
allowReserved: true
schema:
type: string
example: items,series
responses:
'200':
description: getAuthorById OK
content:
application/json:
schema:
$ref: '#/components/schemas/author'
'404':
$ref: '#/components/responses/author404'
patch:
operationId: updateAuthorById
summary: Update an author by ID
description: Update an author by ID. The author's name and description can be updated. This endpoint will merge two authors if the new author name matches another author name in the database.
tags:
- Authors
requestBody:
description: The author object to update.
content:
application/json:
schema:
properties:
name:
$ref: '#/components/schemas/authorName'
description:
$ref: '#/components/schemas/authorDescription'
imagePath:
$ref: '#/components/schemas/authorImagePath'
asin:
$ref: '#/components/schemas/authorAsin'
responses:
'200':
description: updateAuthorById OK
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/author'
- $ref: '#/components/schemas/authorUpdated'
- $ref: '#/components/schemas/authorMerged'
'404':
$ref: '#/components/responses/author404'
delete:
operationId: deleteAuthorById
summary: Delete an author by ID
description: Delete an author by ID. This will remove the author from all books.
tags:
- Authors
responses:
'200':
description: deleteAuthorById OK
content:
text/plain:
schema:
type: string
example: Author deleted.
'404':
$ref: '#/components/responses/author404'
/api/authors/{id}/image:
parameters:
- name: id
in: path
description: Author ID
required: true
schema:
$ref: '#/components/schemas/authorId'
- name: token
in: query
description: API token
schema:
type: string
- name: ts
in: query
description: Updated at value
schema:
type: integer
get:
operationId: getAuthorImageById
summary: Get an author image by author ID
description: Get an author image by author ID. The image will be returned in the requested format and size.
security: []
tags:
- Authors
requestBody:
required: false
description: The author image to get.
content:
application/json:
schema:
properties:
width:
$ref: '#/components/schemas/imageWidth'
height:
$ref: '#/components/schemas/imageHeight'
format:
$ref: '#/components/schemas/imageFormat'
raw:
$ref: '#/components/schemas/imageRaw'
responses:
'200':
description: getAuthorImageById OK
content:
image/webp:
schema:
type: string
format: binary
image/jpeg:
schema:
type: string
format: binary
image/*:
schema:
type: string
format: binary
'404':
$ref: '#/components/responses/author404'
post:
operationId: addAuthorImageById
summary: Add an author image to the server
description: Add an author image to the server. The image will be downloaded from the provided URL and stored on the server.
tags:
- Authors
requestBody:
required: true
description: The author image to add by URL.
content:
application/json:
schema:
$ref: '#/components/schemas/imageUrl'
responses:
'200':
description: addAuthorImageById OK
content:
image/*:
schema:
type: string
format: binary
'404':
$ref: '#/components/responses/author404'
patch:
operationId: updateAuthorImageById
summary: Update an author image by author ID
description: Update an author image by author ID. The image will be resized if the width, height, or format is provided.
tags:
- Authors
requestBody:
description: The author image to update.
content:
application/json:
schema:
properties:
width:
$ref: '#/components/schemas/imageWidth'
height:
$ref: '#/components/schemas/imageHeight'
format:
$ref: '#/components/schemas/imageFormat'
raw:
$ref: '#/components/schemas/imageRaw'
responses:
'200':
description: updateAuthorImageById OK
content:
image/*:
schema:
type: string
format: binary
'404':
$ref: '#/components/responses/author404'
delete:
operationId: deleteAuthorImageById
summary: Delete an author image by author ID
description: Delete an author image by author ID. This will remove the image from the server and the database.
tags:
- Authors
responses:
'200':
description: deleteAuthorImageById OK
'404':
$ref: '#/components/responses/author404'
/api/authors/{id}/match:
parameters:
- name: id
in: path
description: Author ID
required: true
schema:
$ref: '#/components/schemas/authorId'
post:
operationId: matchAuthorById
summary: Match the author against Audible using quick match
description: Match the author against Audible using quick match. Quick match updates the author's description and image (if no image already existed) with information from audible. Either `asin` or `q` must be provided, with `asin` taking priority if both are provided.
tags:
- Authors
requestBody:
required: true
description: The author object to match against an online provider.
content:
application/json:
schema:
type: object
properties:
q:
$ref: '#/components/schemas/authorSearchName'
asin:
$ref: '#/components/schemas/authorAsin'
region:
$ref: '#/components/schemas/region'
responses:
'200':
description: matchAuthorById OK
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/author'
- $ref: '#/components/schemas/authorUpdated'
'404':
$ref: '#/components/responses/author404'
/api/emails/settings:
get:
summary: Get email settings
description: Get email settings for sending e-books to e-readers.
operationId: getEmailSettings
tags:
- Email
responses:
'200':
$ref: '#/components/responses/email200'
patch:
summary: Update email settings
operationId: updateEmailSettings
tags:
- Email
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EmailSettings'
responses:
'200':
$ref: '#/components/responses/email200'
/api/emails/test:
post:
summary: Send test email
operationId: sendTestEmail
tags:
- Email
responses:
'200':
description: Successful response
/api/emails/ereader-devices:
post:
summary: Update e-reader devices
operationId: updateEReaderDevices
tags:
- Email
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
ereaderDevices:
type: array
items:
$ref: '#/components/schemas/EreaderDeviceObject'
responses:
'200':
$ref: '#/components/responses/ereader200'
'400':
description: Invalid payload
/api/emails/send-ebook-to-device:
post:
summary: Send ebook to device
operationId: sendEBookToDevice
tags:
- Email
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
libraryItemId:
$ref: '#/components/schemas/libraryItemId'
deviceName:
$ref: '#/components/schemas/ereaderName'
responses:
'200':
description: Successful response
'400':
description: Invalid request
'403':
description: Forbidden
'404':
description: Not found
/api/libraries:
get:
operationId: getLibraries
summary: Get all libraries on server
description: Get all libraries on server.
tags:
- Libraries
responses:
'200':
description: getLibraries OK
content:
application/json:
schema:
type: object
properties:
libraries:
type: array
items:
$ref: '#/components/schemas/library'
post:
operationId: createLibrary
summary: Create a new library on server
description: Create a new library on server.
tags:
- Libraries
requestBody:
description: The library object to create.
content:
application/json:
schema:
type: object
required:
- name
- folders
properties:
name:
$ref: '#/components/schemas/libraryName'
folders:
$ref: '#/components/schemas/libraryFolders'
displayOrder:
$ref: '#/components/schemas/libraryDisplayOrder'
icon:
$ref: '#/components/schemas/libraryIcon'
mediaType:
$ref: '#/components/schemas/libraryMediaType'
provider:
$ref: '#/components/schemas/libraryProvider'
settings:
$ref: '#/components/schemas/librarySettings'
responses:
'200':
$ref: '#/components/responses/library200'
'404':
$ref: '#/components/responses/library404'
/api/libraries/{id}:
parameters:
- name: id
in: path
description: The ID of the library.
required: true
schema:
$ref: '#/components/schemas/libraryId'
get:
operationId: getLibraryById
summary: Get a single library by ID on server
description: Get a single library by ID on server.
tags:
- Libraries
parameters:
- in: query
name: include
description: A comma separated list of what to include with the library item. The only current option is filterdata.
schema:
type: string
- $ref: '#/components/parameters/minified'
responses:
'200':
$ref: '#/components/responses/library200'
'404':
$ref: '#/components/responses/library404'
patch:
operationId: updateLibraryById
summary: Update a single library by ID on server
description: Update a single library by ID on server.
tags:
- Libraries
requestBody:
required: true
description: The library object to update.
content:
application/json:
schema:
type: object
properties:
name:
$ref: '#/components/schemas/libraryName'
folders:
$ref: '#/components/schemas/libraryFolders'
displayOrder:
$ref: '#/components/schemas/libraryDisplayOrder'
icon:
$ref: '#/components/schemas/libraryIcon'
mediaType:
$ref: '#/components/schemas/libraryMediaType'
provider:
$ref: '#/components/schemas/libraryProvider'
settings:
$ref: '#/components/schemas/librarySettings'
responses:
'200':
$ref: '#/components/responses/library200'
'404':
$ref: '#/components/responses/library404'
delete:
operationId: deleteLibraryById
summary: Delete a single library by ID on server
description: Delete a single library by ID on server and return the deleted object.
tags:
- Libraries
responses:
'200':
$ref: '#/components/responses/library200'
'404':
$ref: '#/components/responses/library404'
/api/libraries/{id}/authors:
parameters:
- name: id
in: path
description: The ID of the library.
required: true
schema:
$ref: '#/components/schemas/libraryId'
get:
operationId: getLibraryAuthors
summary: Get all authors in a library
description: Get all authors in a library by ID on server.
tags:
- Libraries
responses:
'200':
description: getLibraryAuthors OK
content:
application/json:
schema:
type: object
properties:
authors:
type: array
items:
$ref: '#/components/schemas/authorExpanded'
'404':
$ref: '#/components/responses/library404'
/api/libraries/{id}/items:
parameters:
- name: id
in: path
description: The ID of the library.
required: true
schema:
$ref: '#/components/schemas/libraryId'
get:
operationId: getLibraryItems
summary: Get items in a library
description: Get items in a library by ID on server.
tags:
- Libraries
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page'
- in: query
name: sort
description: The field to sort by from the request.
example: numBooks
schema:
type: string
default: name
- $ref: '#/components/parameters/desc'
- in: query
name: filter
description: The filter for the library.
example: media.metadata.title
schema:
type: string
- in: query
name: include
description: The fields to include in the response. The only current option is `rssfeed`.
allowReserved: true
example: rssfeed
schema:
type: string
- $ref: '#/components/parameters/minified'
- in: query
name: collapseSeries
description: Whether to collapse series into a single cover
schema:
type: integer
default: 0
responses:
'200':
description: getLibraryItems OK
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/libraryItemBase'
total:
$ref: '#/components/schemas/total'
limit:
$ref: '#/components/schemas/limit'
page:
$ref: '#/components/schemas/page'
sortBy:
$ref: '#/components/schemas/sortBy'
sortDesc:
$ref: '#/components/schemas/sortDesc'
filterBy:
$ref: '#/components/schemas/filterBy'
mediaType:
$ref: '#/components/schemas/mediaType'
minified:
$ref: '#/components/schemas/minified'
collapseSeries:
$ref: '#/components/schemas/collapseSeries'
include:
$ref: '#/components/schemas/libraryInclude'
'404':
$ref: '#/components/responses/library404'
/api/libraries/{id}/issues:
parameters:
- name: id
in: path
description: The ID of the library.
required: true
schema:
$ref: '#/components/schemas/libraryId'
delete:
operationId: deleteLibraryIssues
summary: Delete items with issues in a library.
description: Delete all items with issues in a library by library ID on the server. This only removes the items from the ABS database and does not delete media files.
tags:
- Libraries
responses:
'200':
description: deleteLibraryIssues OK
content:
application/json:
schema:
type: string
example: Issues deleted.
'404':
$ref: '#/components/responses/library404'
/api/libraries/{id}/series:
parameters:
- name: id
in: path
description: The ID of the library.
required: true
schema:
$ref: '#/components/schemas/libraryId'
get:
operationId: getLibrarySeries
summary: Get library series
description: Get series in a library. Filtering and sorting can be applied.
tags:
- Libraries
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page'
- in: query
name: sort
description: The field to sort by from the request.
example: numBooks
schema:
type: string
enum:
- name
- numBooks
- totalDuration
- addedAt
- lastBookAdded
- lastBookUpdated
default: name
- $ref: '#/components/parameters/desc'
- in: query
name: filter
description: The filter for the library.
example: media.metadata.title
schema:
type: string
- in: query
name: include
description: The fields to include in the response. The only current option is `rssfeed`.
allowReserved: true
example: rssfeed
schema:
type: string
- $ref: '#/components/parameters/minified'
responses:
'200':
description: getLibrarySeries OK
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/seriesBooks'
total:
$ref: '#/components/schemas/total'
limit:
$ref: '#/components/schemas/limit'
page:
$ref: '#/components/schemas/page'
sortBy:
$ref: '#/components/schemas/sortBy'
sortDesc:
$ref: '#/components/schemas/sortDesc'
filterBy:
$ref: '#/components/schemas/filterBy'
minified:
$ref: '#/components/schemas/minified'
include:
$ref: '#/components/schemas/libraryInclude'
'404':
$ref: '#/components/responses/library404'
/api/libraries/{id}/series/{seriesId}:
parameters:
- name: id
in: path
description: The ID of the library.
required: true
schema:
$ref: '#/components/schemas/libraryId'
- name: seriesId
in: path
description: The ID of the series.
required: true
schema:
$ref: '#/components/schemas/seriesId'
get:
operationId: getLibrarySeriesById
summary: Get single series in library
description: Get a single series in a library by ID on server. This endpoint is deprecated and `/api/series/{id}` should be used instead.
deprecated: true
tags:
- Libraries
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page'
- in: query
name: sort
description: The field to sort by from the request.
example: numBooks
schema:
type: string
enum:
- name
- numBooks
- totalDuration
- addedAt
- lastBookAdded
- lastBookUpdated
default: name
- $ref: '#/components/parameters/desc'
- in: query
name: filter
description: The filter for the library.
example: media.metadata.title
schema:
type: string
- $ref: '#/components/parameters/minified'
- in: query
name: include
description: The fields to include in the response. The only current option is `rssfeed`.
allowReserved: true
example: rssfeed
schema:
type: string
responses:
'200':
description: getLibrarySeriesById OK
content:
application/json:
schema:
$ref: '#/components/schemas/seriesWithProgressAndRSS'
'404':
$ref: '#/components/responses/library404'
/api/notifications:
get:
operationId: getNotifications
summary: Get notification settings
description: Get all Apprise notification events and notification settings for server.
tags:
- Notification
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
events:
type: array
items:
$ref: '#/components/schemas/NotificationEvent'
settings:
$ref: '#/components/schemas/NotificationSettings'
'404':
$ref: '#/components/responses/notification404'
patch:
operationId: configureNotificationSettings
summary: Update select notification settings
description: Update the URL, max failed attempts, and maximum notifications that can be queued for Apprise.
tags:
- Notification
requestBody:
content:
application/json:
schema:
type: object
properties:
appriseApiUrl:
$ref: '#/components/schemas/appriseApiUrl'
maxFailedAttempts:
$ref: '#/components/schemas/maxFailedAttempts'
maxNotificationQueue:
$ref: '#/components/schemas/maxNotificationQueue'
responses:
'200':
$ref: '#/components/responses/notification200'
'404':
$ref: '#/components/responses/notification404'
post:
operationId: createNotification
summary: Create notification settings
description: Create or update Notification settings.
tags:
- Notification
requestBody:
content:
application/json:
schema:
type: object
properties:
libraryId:
$ref: '#/components/schemas/libraryIdNullable'
eventName:
$ref: '#/components/schemas/notificationEventName'
urls:
$ref: '#/components/schemas/urls'
titleTemplate:
$ref: '#/components/schemas/titleTemplate'
bodyTemplate:
$ref: '#/components/schemas/bodyTemplate'
enabled:
$ref: '#/components/schemas/enabled'
type:
$ref: '#/components/schemas/notificationType'
required:
- eventName
- urls
- titleTemplate
- bodyTemplate
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
settings:
$ref: '#/components/schemas/NotificationSettings'
'404':
$ref: '#/components/responses/notification404'
/api/notificationdata:
get:
operationId: getNotificationEventData
summary: Get notification event data
description: Get all Apprise notification event data for the server.
tags:
- Notification
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
events:
type: array
items:
$ref: '#/components/schemas/NotificationEvent'
'404':
$ref: '#/components/responses/notification404'
/api/notifications/test:
get:
operationId: sendDefaultTestNotification
summary: Send general test notification
description: Send a test notification.
tags:
- Notification
parameters:
- in: query
name: fail
description: Whether to intentionally cause the notification to fail. `0` for false, `1` for true.
schema:
type: integer
responses:
'200':
$ref: '#/components/responses/notification200'
'404':
$ref: '#/components/responses/notification404'
/api/notifications/{id}:
parameters:
- name: id
in: path
description: The ID of the notification.
required: true
schema:
$ref: '#/components/schemas/notificationId'
delete:
operationId: deleteNotification
summary: Delete a notification
description: Delete the notification by ID and return the notification settings.
tags:
- Notification
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
settings:
$ref: '#/components/schemas/NotificationSettings'
'404':
$ref: '#/components/responses/notification404'
patch:
operationId: updateNotification
summary: Update a notification
description: Update an individual Notification by ID
tags:
- Notification
requestBody:
content:
application/json:
schema:
type: object
properties:
libraryId:
$ref: '#/components/schemas/libraryId'
eventName:
$ref: '#/components/schemas/notificationEventName'
urls:
$ref: '#/components/schemas/urls'
titleTemplate:
$ref: '#/components/schemas/titleTemplate'
bodyTemplate:
$ref: '#/components/schemas/bodyTemplate'
enabled:
$ref: '#/components/schemas/enabled'
type:
$ref: '#/components/schemas/notificationType'
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
settings:
$ref: '#/components/schemas/NotificationSettings'
'404':
$ref: '#/components/responses/notification404'
/api/notifications/{id}/test:
parameters:
- name: id
in: path
description: The ID of the notification.
required: true
schema:
$ref: '#/components/schemas/notificationId'
get:
operationId: sendTestNotification
summary: Send a test notification
description: Send a test to the given notification by ID.
tags:
- Notification
responses:
'200':
$ref: '#/components/responses/notification200'
'404':
$ref: '#/components/responses/notification404'
/api/podcasts:
post:
summary: Create a new podcast
operationId: createPodcast
tags:
- Podcasts
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Podcast'
responses:
'200':
description: Successfully created a podcast
content:
application/json:
schema:
$ref: '#/components/schemas/Podcast'
'400':
description: Bad request
'403':
description: Forbidden
'404':
description: Not found
/api/podcasts/feed:
post:
summary: Get podcast feed
operationId: getPodcastFeed
tags:
- Podcasts
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
rssFeed:
type: string
description: The RSS feed URL of the podcast
responses:
'200':
description: Successfully retrieved podcast feed
content:
application/json:
schema:
type: object
properties:
podcast:
$ref: '#/components/schemas/Podcast'
'400':
description: Bad request
'403':
description: Forbidden
'404':
description: Not found
/api/podcasts/opml/parse:
post:
summary: Get feeds from OPML text
description: Parse OPML text and return an array of feeds
operationId: getFeedsFromOPMLText
tags:
- Podcasts
requestBody:
content:
application/json:
schema:
type: object
properties:
opmlText:
type: string
responses:
'200':
description: Successfully parsed OPML text and returned feeds
content:
application/json:
schema:
type: object
properties:
feeds:
type: array
items:
type: object
properties:
title:
type: string
feedUrl:
type: string
'400':
description: Bad request, OPML text not provided
'403':
description: Forbidden, user is not admin
/api/podcasts/opml/create:
post:
summary: Bulk create podcasts from OPML feed URLs
operationId: bulkCreatePodcastsFromOpmlFeedUrls
tags:
- Podcasts
requestBody:
content:
application/json:
schema:
type: object
properties:
feeds:
type: array
items:
type: string
libraryId:
$ref: '#/components/schemas/libraryId'
folderId:
$ref: '#/components/schemas/folderId'
autoDownloadEpisodes:
$ref: '#/components/schemas/autoDownloadEpisodes'
responses:
'200':
description: Successfully created podcasts from feed URLs
'400':
description: Bad request, invalid request body
'403':
description: Forbidden, user is not admin
'404':
description: Folder not found
/api/podcasts/{id}/checknew:
parameters:
- name: id
in: path
description: Podcast ID
required: true
schema:
$ref: '#/components/schemas/podcastId'
get:
summary: Check and download new episodes
operationId: checkNewEpisodes
tags:
- Podcasts
parameters:
- name: limit
in: query
description: Maximum number of episodes to download
required: false
schema:
type: integer
responses:
'200':
description: Successfully checked and downloaded new episodes
content:
application/json:
schema:
type: object
properties:
episodes:
type: array
items:
$ref: '#/components/schemas/PodcastEpisode'
'403':
description: Forbidden
'404':
description: Not found
'500':
description: Server error
/api/podcasts/{id}/clear-queue:
parameters:
- name: id
in: path
description: Podcast ID
required: true
schema:
$ref: '#/components/schemas/podcastId'
get:
summary: Clear episode download queue
operationId: clearEpisodeDownloadQueue
tags:
- Podcasts
responses:
'200':
description: Successfully cleared download queue
'403':
description: Forbidden
/api/podcasts/{id}/downloads:
parameters:
- name: id
in: path
description: Podcast ID
required: true
schema:
$ref: '#/components/schemas/podcastId'
get:
summary: Get episode downloads
operationId: getEpisodeDownloads
tags:
- Podcasts
responses:
'200':
description: Successfully retrieved episode downloads
content:
application/json:
schema:
type: object
properties:
downloads:
type: array
items:
$ref: '#/components/schemas/PodcastEpisode'
'404':
description: Not found
/api/podcasts/{id}/search-episode:
parameters:
- name: id
in: path
description: Podcast ID
required: true
schema:
$ref: '#/components/schemas/podcastId'
get:
summary: Find episode by title
operationId: findEpisode
tags:
- Podcasts
parameters:
- name: title
in: query
description: Title of the episode to search for
required: true
schema:
type: string
responses:
'200':
description: Successfully found episodes
content:
application/json:
schema:
type: object
properties:
episodes:
type: array
items:
$ref: '#/components/schemas/PodcastEpisode'
'404':
description: Not found
'500':
description: Server error
/api/podcasts/{id}/download-episodes:
parameters:
- name: id
in: path
description: Podcast ID
required: true
schema:
$ref: '#/components/schemas/podcastId'
post:
summary: Download podcast episodes
operationId: downloadEpisodes
tags:
- Podcasts
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
type: string
responses:
'200':
description: Successfully started episode download
'400':
description: Bad request
'403':
description: Forbidden
/api/podcasts/{id}/match-episodes:
parameters:
- name: id
in: path
description: Podcast ID
required: true
schema:
$ref: '#/components/schemas/podcastId'
post:
summary: Quick match podcast episodes
operationId: quickMatchEpisodes
tags:
- Podcasts
parameters:
- name: override
in: query
description: Override existing details if set to 1
required: false
schema:
type: string
responses:
'200':
description: Successfully matched episodes
content:
application/json:
schema:
type: object
properties:
numEpisodesUpdated:
type: integer
'403':
description: Forbidden
/api/podcasts/{id}/episode/{episodeId}:
parameters:
- name: id
in: path
description: Podcast ID
required: true
schema:
$ref: '#/components/schemas/podcastId'
- name: episodeId
in: path
description: Episode ID
required: true
schema:
$ref: '#/components/schemas/podcastId'
patch:
summary: Update a podcast episode
operationId: updateEpisode
tags:
- Podcasts
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'200':
description: Successfully updated episode
content:
application/json:
schema:
$ref: '#/components/schemas/Podcast'
'404':
description: Not found
get:
summary: Get a specific podcast episode
operationId: getEpisode
tags:
- Podcasts
responses:
'200':
description: Successfully retrieved episode
content:
application/json:
schema:
$ref: '#/components/schemas/PodcastEpisode'
'404':
description: Not found
delete:
summary: Remove a podcast episode
operationId: removeEpisode
tags:
- Podcasts
parameters:
- name: hard
in: query
description: Hard delete the episode if set to 1
required: false
schema:
type: string
responses:
'200':
description: Successfully removed episode
content:
application/json:
schema:
$ref: '#/components/schemas/Podcast'
'404':
description: Not found
'500':
description: Server error
/api/series/{id}:
parameters:
- name: id
in: path
description: The ID of the series.
required: true
schema:
$ref: '#/components/schemas/seriesId'
get:
operationId: getSeries
tags:
- Series
summary: Get series
description: Get a series by ID.
requestBody:
required: false
description: A comma separated list of what to include with the series.
content:
application/json:
schema:
type: object
properties:
include:
type: string
description: A comma separated list of what to include with the series.
example: progress,rssfeed
enum:
- progress
- rssfeed
- progress,rssfeed
- rssfeed,progress
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/seriesWithProgressAndRSS'
'404':
$ref: '#/components/responses/series404'
patch:
operationId: updateSeries
tags:
- Series
summary: Update series
description: Update a series by ID.
requestBody:
required: true
description: The series to update.
content:
application/json:
schema:
properties:
name:
$ref: '#/components/schemas/seriesName'
description:
$ref: '#/components/schemas/seriesDescription'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/series'
'404':
$ref: '#/components/responses/series404'
/login:
post:
summary: Login to the server
description: Logs in a client to the server, returning information about the user and server.
operationId: login
tags:
- Auth
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
username:
$ref: '#/components/schemas/username'
password:
$ref: '#/components/schemas/password'
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
user:
$ref: '#/components/schemas/user'
'401':
description: Unauthorized - Invalid username or password.
content:
text/html:
schema:
type: string
example: Unauthorized
/logout:
post:
summary: Logout from the server
description: Logs out a client from the server. If the socketId parameter is provided, the server removes the socket from the client list.
operationId: logout
tags:
- Auth
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
socketId:
$ref: '#/components/schemas/socketId'
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Success
'401':
description: Unauthorized
content:
text/html:
schema:
type: string
example: Unauthorized
/api/items/{id}:
parameters:
- name: id
in: path
description: The ID of the library item.
required: true
schema:
$ref: '#/components/schemas/libraryItemId'
get:
operationId: getLibraryItem
summary: Get a single library item by ID on server.
description: Get a single library item by ID on server.
tags:
- LibraryItem
parameters:
- $ref: '#/components/parameters/include'
- $ref: '#/components/parameters/expanded'
- $ref: '#/components/parameters/episode'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
description: TODO
oneOf:
- $ref: '#/components/schemas/libraryItem'
'404':
$ref: '#/components/responses/libraryItem404'
/api/items/{id}/play:
parameters:
- name: id
in: path
description: The ID of the library item.
required: true
schema:
$ref: '#/components/schemas/libraryItemId'
post:
operationId: playLibraryItem
summary: Play a library item
description: Play a library item by ID.
tags:
- LibraryItem
requestBody:
required: true
content:
application/json:
schema:
properties:
deviceInfo:
$ref: '#/components/schemas/deviceInfo'
forceDirectPlay:
$ref: '#/components/schemas/forceDirectPlay'
forceTranscode:
$ref: '#/components/schemas/forceTranscode'
supportedMimeTypes:
$ref: '#/components/schemas/supportedMimeTypes'
mediaPlayer:
$ref: '#/components/schemas/mediaPlayer'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/playbackSessionExpanded'
'404':
$ref: '#/components/responses/libraryItem404'
/api/items/{id}/play/{episodeId}:
parameters:
- name: id
in: path
description: The ID of the library item.
required: true
schema:
$ref: '#/components/schemas/libraryItemId'
- name: episodeId
in: path
description: The ID of the episode to play.
required: true
schema:
$ref: '#/components/schemas/podcastId'
post:
operationId: playLibraryItemPodcastEpisode
summary: Play a podcast episode
description: Play a podcast by library item ID and episode ID.
tags:
- LibraryItem
requestBody:
required: true
content:
application/json:
schema:
properties:
deviceInfo:
$ref: '#/components/schemas/deviceInfo'
forceDirectPlay:
$ref: '#/components/schemas/forceDirectPlay'
forceTranscode:
$ref: '#/components/schemas/forceTranscode'
supportedMimeTypes:
$ref: '#/components/schemas/supportedMimeTypes'
mediaPlayer:
$ref: '#/components/schemas/mediaPlayer'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/playbackSessionExpanded'
'404':
$ref: '#/components/responses/libraryItem404'
/api/me:
get:
operationId: getMe
summary: Get the current user.
description: Get the current user.
tags:
- Me
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/user'
/api/me/progress/{libraryItemId}:
parameters:
- name: libraryItemId
in: path
description: The ID of the library item.
required: true
schema:
$ref: '#/components/schemas/libraryItemId'
get:
operationId: getProgressLibraryItem
summary: Get the user's progress for a library item.
description: Get the user's progress for a library item.
tags:
- Me
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/mediaProgress'
'404':
$ref: '#/components/responses/me404'
/api/me/progress/{libraryItemId}/{episodeId}:
parameters:
- name: libraryItemId
in: path
description: The ID of the library item.
required: true
schema:
$ref: '#/components/schemas/libraryItemId'
- name: episodeId
in: path
description: The ID of the episode to get progress for.
required: true
schema:
$ref: '#/components/schemas/podcastId'
get:
operationId: getProgressPodcastEpisode
summary: Get the user's progress for a podcast episode.
description: Get the user's progress for a podcast episode.
tags:
- Me
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/mediaProgressPodcastEpisode'
'404':
$ref: '#/components/responses/me404'
/api/session/{id}/sync:
post:
operationId: syncOpenSession
summary: Sync an open session.
description: Sync an open session.
tags:
- Session
parameters:
- name: id
in: path
description: The ID of the session.
required: true
schema:
$ref: '#/components/schemas/playbackSessionId'
requestBody:
required: true
content:
application/json:
schema:
properties:
id:
$ref: '#/components/schemas/playbackSessionId'
currentTime:
$ref: '#/components/schemas/durationSec'
timeListened:
$ref: '#/components/schemas/durationSec'
duration:
$ref: '#/components/schemas/durationSec'
responses:
'200':
description: OK
content:
html/text:
schema:
type: string
example: OK
'404':
description: No listening session with the provided ID is open, or the session belongs to another user.
content:
html/text:
schema:
type: string
example: Not Found
'500':
description: There was an error syncing the session.
content:
html/text:
schema:
type: string
example: Internal Server Error
/api/sessions/{id}:
delete:
operationId: deleteSession
summary: Delets a listening session.
description: Deletes a listening session.
tags:
- Session
parameters:
- name: id
in: path
description: The ID of the session.
required: true
schema:
$ref: '#/components/schemas/playbackSessionId'
responses:
'200':
description: OK
content:
html/text:
schema:
type: string
example: OK
'403':
description: A user with delete permissions is required to delete sessions.
content:
html/text:
schema:
type: string
example: Forbidden
'404':
description: No listening session with the provided ID was found.
content:
html/text:
schema:
type: string
example: Not Found
/api/session/{id}/close:
post:
operationId: closeSession
summary: Close a listening session.
description: Close a listening session.
tags:
- Session
parameters:
- name: id
in: path
description: The ID of the session.
required: true
schema:
$ref: '#/components/schemas/playbackSessionId'
- name: currentTime
in: query
description: The current time of the session.
required: false
schema:
$ref: '#/components/schemas/durationSec'
- name: timeListened
in: query
description: The time listened to the session.
required: false
schema:
$ref: '#/components/schemas/durationSec'
- name: duration
in: query
description: The duration of the session.
required: false
schema:
$ref: '#/components/schemas/durationSec'
responses:
'200':
description: OK
content:
html/text:
schema:
type: string
example: OK
'404':
description: No listening session with the provided ID is open, or the session belongs to another user.
content:
html/text:
schema:
type: string
example: Not Found
/api/session/{id}:
get:
operationId: getSession
summary: Get a listening session.
description: Get a listening session.
tags:
- Session
parameters:
- name: id
in: path
description: The ID of the session.
required: true
schema:
$ref: '#/components/schemas/playbackSessionId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/playbackSessionExpanded'
'404':
description: No listening session with the provided ID was found.
content:
html/text:
schema:
type: string
example: Not Found
/api/sessions:
get:
operationId: getSessions
summary: Get all listening sessions.
description: Get all listening sessions.
tags:
- Session
parameters:
- name: user
in: query
description: The ID of the user to filter listening sessions by.
required: false
schema:
$ref: '#/components/schemas/userId'
- name: itemsPerPage
in: query
description: The number of items to return.
required: false
schema:
$ref: '#/components/schemas/limit'
- name: page
in: query
description: The page number (zero indexed) to return.
required: false
schema:
$ref: '#/components/schemas/page'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/libraryItemBase'
total:
$ref: '#/components/schemas/total'
itemsPerPage:
$ref: '#/components/schemas/limit'
numPages:
description: The number of pages.
type: integer
example: 10
userFilter:
description: If provided, the `user` parameter.
sessions:
type: array
items:
$ref: '#/components/schemas/playbackSession'
'404':
description: No listening sessions were found.
content:
html/text:
schema:
type: string
example: Not Found
/api/me/listening-sessions:
get:
operationId: getListeningSessions
summary: Get all listening sessions for the current user.
description: Get all listening sessions for the current user.
tags:
- Me
parameters:
- name: itemsPerPage
in: query
description: The number of items per page.
required: true
schema:
$ref: '#/components/schemas/limit'
- name: page
in: query
description: The page number (zero indexed) to return.
required: true
schema:
$ref: '#/components/schemas/page'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
total:
$ref: '#/components/schemas/total'
numPages:
description: The number of pages.
type: integer
itemsPerPage:
$ref: '#/components/schemas/limit'
sessions:
type: array
items:
$ref: '#/components/schemas/playbackSession'
/api/me/listening-stats:
get:
operationId: getListeningStats
summary: Get listening stats for the current user.
description: Get listening stats for the current user.
tags:
- Me
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
totalTime:
$ref: '#/components/schemas/totalTime'
items:
type: object
description: A list of library items the user has listened to, keyed by their item IDs.
additionalProperties:
type: object
properties:
id:
type: string
description: The ID of the library item.
timeListening:
type: number
description: The time (in seconds) the user listened to this library item.
mediaMetadata:
oneOf:
- $ref: '#/components/schemas/bookMetadata'
days:
type: object
description: A mapping of days to total listening times.
additionalProperties:
type: number
description: The total time (in seconds) listened to on that day.
dayOfWeek:
type: object
description: A mapping of days of the week to total listening times.
additionalProperties:
type: number
description: The total time (in seconds) listened to on that day of the week.
today:
type: number
description: The time (in seconds) the user has listened to library items today.
recentSessions:
type: array
items:
$ref: '#/components/schemas/playbackSession'
/api/session/local:
post:
operationId: createLocalSession
summary: Create a local session.
description: Create a local session.
tags:
- Session
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/playbackSession'
responses:
'200':
description: OK
content:
html/text:
schema:
type: string
example: OK
'500':
description: There was an error creating the session.
content:
html/text:
schema:
type: string
example: Internal Server Error
/api/local/session/local-all:
post:
operationId: createLocalSessionAll
summary: Create a local session for all users.
description: Create a local session for all users.
tags:
- Session
requestBody:
required: true
content:
application/json:
schema:
items:
$ref: '#/components/schemas/playbackSession'
responses:
'200':
description: OK
content:
html/text:
schema:
type: string
example: OK
'500':
description: There was an error creating the session.
content:
html/text:
schema:
type: string
example: Internal Server Error
components:
securitySchemes:
BearerAuth:
description: Bearer authentication
type: http
scheme: bearer
schemas:
authorId:
type: string
description: The ID of the author.
format: uuid
example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
authorAsin:
description: The Audible identifier (ASIN) of the author. Will be null if unknown. Not the Amazon identifier.
type: string
nullable: true
example: B000APZOQA
authorName:
description: The name of the author.
type: string
example: Terry Goodkind
authorDescription:
description: The new description of the author.
type: string
nullable: true
example: Terry Goodkind is a
authorImagePath:
description: The absolute path for the author image. This will be in the `metadata/` directory. Will be null if there is no image.
type: string
nullable: true
example: /metadata/authors/aut_z3leimgybl7uf3y4ab.jpg
addedAt:
type: integer
description: The time (in ms since POSIX epoch) when added to the server.
example: 1633522963509
updatedAt:
type: integer
description: The time (in ms since POSIX epoch) when last updated.
example: 1633522963509
libraryItemId:
type: string
description: The ID of library items after 2.3.0.
format: uuid
example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
oldLibraryItemId:
description: The ID of library items on server version 2.2.23 and before.
type: string
nullable: true
format: li_[a-z0-9]{18}
example: li_o78uaoeuh78h6aoeif
inode:
description: The inode of the item in the file system.
type: string
format: '[0-9]*'
example: '649644248522215260'
libraryId:
type: string
description: The ID of the library.
format: uuid
example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
folderId:
type: string
description: The ID of the folder.
format: uuid
example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
mediaType:
type: string
description: The type of media, will be book or podcast.
enum:
- book
- podcast
bookCoverPath:
description: The absolute path on the server of the cover file. Will be null if there is no cover.
type: string
nullable: true
example: /audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/cover.jpg
tags:
description: Tags applied to items.
type: array
items:
type: string
example:
- To Be Read
- 'Genre: Nonfiction'
size:
description: The total size (in bytes) of the item or file.
type: integer
example: 268824228
fileMetadata:
type: object
description: The metadata for a file, including the path, size, and unix timestamps of the file.
nullable: true
properties:
filename:
description: The filename of the file.
type: string
example: Wizards First Rule 01.mp3
ext:
description: The file extension of the file.
type: string
example: .mp3
path:
description: The absolute path on the server of the file.
type: string
example: /audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3
relPath:
description: The path of the file, relative to the book's or podcast's folder.
type: string
example: Wizards First Rule 01.mp3
size:
$ref: '#/components/schemas/size'
mtimeMs:
description: The time (in ms since POSIX epoch) when the file was last modified on disk.
type: integer
example: 1632223180278
ctimeMs:
description: The time (in ms since POSIX epoch) when the file status was changed on disk.
type: integer
example: 1645978261001
birthtimeMs:
description: The time (in ms since POSIX epoch) when the file was created on disk. Will be 0 if unknown.
type: integer
example: 0
durationSec:
description: The total length (in seconds) of the item or file.
type: number
example: 33854.905
bookChapter:
type: object
description: A book chapter. Includes the title and timestamps.
nullable: true
properties:
id:
description: The ID of the book chapter.
type: integer
example: 0
start:
description: When in the book (in seconds) the chapter starts.
type: number
example: 0
end:
description: When in the book (in seconds) the chapter ends.
type: number
example: 6004.6675
title:
description: The title of the chapter.
type: string
example: Wizards First Rule 01 Chapter 1
audioMetaTags:
description: ID3 metadata tags pulled from the audio file on import. Only non-null tags will be returned in requests.
type: object
properties:
tagAlbum:
type: string
nullable: true
example: SOT Bk01
tagArtist:
type: string
nullable: true
example: Terry Goodkind
tagGenre:
type: string
nullable: true
example: Audiobook Fantasy
tagTitle:
type: string
nullable: true
example: Wizards First Rule 01
tagSeries:
type: string
nullable: true
tagSeriesPart:
type: string
nullable: true
tagTrack:
type: string
nullable: true
example: 01/20
tagDisc:
type: string
nullable: true
tagSubtitle:
type: string
nullable: true
tagAlbumArtist:
type: string
nullable: true
example: Terry Goodkind
tagDate:
type: string
nullable: true
tagComposer:
type: string
nullable: true
example: Terry Goodkind
tagPublisher:
type: string
nullable: true
tagComment:
type: string
nullable: true
tagDescription:
type: string
nullable: true
tagEncoder:
type: string
nullable: true
tagEncodedBy:
type: string
nullable: true
tagIsbn:
type: string
nullable: true
tagLanguage:
type: string
nullable: true
tagASIN:
type: string
nullable: true
tagOverdriveMediaMarker:
type: string
nullable: true
tagOriginalYear:
type: string
nullable: true
tagReleaseCountry:
type: string
nullable: true
tagReleaseType:
type: string
nullable: true
tagReleaseStatus:
type: string
nullable: true
tagISRC:
type: string
nullable: true
tagMusicBrainzTrackId:
type: string
nullable: true
tagMusicBrainzAlbumId:
type: string
nullable: true
tagMusicBrainzAlbumArtistId:
type: string
nullable: true
tagMusicBrainzArtistId:
type: string
nullable: true
audioFile:
type: object
description: An audio file for a book. Includes audio metadata and track numbers.
properties:
index:
description: The index of the audio file.
type: integer
example: 1
ino:
$ref: '#/components/schemas/inode'
metadata:
$ref: '#/components/schemas/fileMetadata'
addedAt:
$ref: '#/components/schemas/addedAt'
updatedAt:
$ref: '#/components/schemas/updatedAt'
trackNumFromMeta:
description: The track number of the audio file as pulled from the file's metadata. Will be null if unknown.
type: integer
nullable: true
example: 1
discNumFromMeta:
description: The disc number of the audio file as pulled from the file's metadata. Will be null if unknown.
type: string
nullable: true
trackNumFromFilename:
description: The track number of the audio file as determined from the file's name. Will be null if unknown.
type: integer
nullable: true
example: 1
discNumFromFilename:
description: The disc number of the audio file as determined from the file's name. Will be null if unknown.
type: string
nullable: true
manuallyVerified:
description: Whether the audio file has been manually verified by a user.
type: boolean
invalid:
description: Whether the audio file is missing from the server.
type: boolean
exclude:
description: Whether the audio file has been marked for exclusion.
type: boolean
error:
description: Any error with the audio file. Will be null if there is none.
type: string
nullable: true
format:
description: The format of the audio file.
type: string
example: MP2/3 (MPEG audio layer 2/3)
duration:
$ref: '#/components/schemas/durationSec'
bitRate:
description: The bit rate (in bit/s) of the audio file.
type: integer
example: 64000
language:
description: The language of the audio file.
type: string
nullable: true
codec:
description: The codec of the audio file.
type: string
example: mp3
timeBase:
description: The time base of the audio file.
type: string
example: 1/14112000
channels:
description: The number of channels the audio file has.
type: integer
example: 2
channelLayout:
description: The layout of the audio file's channels.
type: string
example: stereo
chapters:
description: If the audio file is part of an audiobook, the chapters the file contains.
type: array
items:
$ref: '#/components/schemas/bookChapter'
embeddedCoverArt:
description: The type of embedded cover art in the audio file. Will be null if none exists.
type: string
nullable: true
metaTags:
$ref: '#/components/schemas/audioMetaTags'
mimeType:
description: The MIME type of the audio file.
type: string
example: audio/mpeg
ebookFile:
type: object
properties:
ino:
$ref: '#/components/schemas/inode'
metadata:
$ref: '#/components/schemas/fileMetadata'
ebookFormat:
description: The ebook format of the ebook file.
type: string
example: epub
addedAt:
$ref: '#/components/schemas/addedAt'
updatedAt:
$ref: '#/components/schemas/updatedAt'
bookBase:
type: object
description: Base book schema
properties:
id:
description: TODO
type: string
format: uuid
example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
libraryItemId:
$ref: '#/components/schemas/libraryItemId'
coverPath:
$ref: '#/components/schemas/bookCoverPath'
tags:
$ref: '#/components/schemas/tags'
audioFiles:
type: array
items:
$ref: '#/components/schemas/audioFile'
chapters:
type: array
nullable: true
items:
$ref: '#/components/schemas/bookChapter'
missingParts:
description: Any parts missing from the book by track index.
type: array
items:
type: integer
ebookFile:
$ref: '#/components/schemas/ebookFile'
bookMetadataBase:
type: object
description: The base book metadata object for minified, normal, and extended schemas to inherit from.
properties:
title:
description: The title of the book. Will be null if unknown.
type: string
nullable: true
example: Wizards First Rule
subtitle:
description: The subtitle of the book. Will be null if there is no subtitle.
type: string
nullable: true
genres:
description: The genres of the book.
type: array
items:
type: string
example:
- Fantasy
- Sci-Fi
- 'Nonfiction: History'
publishedYear:
description: The year the book was published. Will be null if unknown.
type: string
nullable: true
example: '2008'
publishedDate:
description: The date the book was published. Will be null if unknown.
type: string
nullable: true
publisher:
description: The publisher of the book. Will be null if unknown.
type: string
nullable: true
example: Brilliance Audio
description:
description: A description for the book. Will be null if empty.
type: string
nullable: true
example: The masterpiece that started Terry Goodkind's New York Times bestselling epic Sword of Truth In the aftermath of the brutal murder of his father, a mysterious woman, Kahlan Amnell, appears in Richard Cypher's forest sanctuary seeking help...and more. His world, his very beliefs, are shattered when ancient debts come due with thundering violence. In a dark age it takes courage to live, and more than mere courage to challenge those who hold dominion, Richard and Kahlan must take up that challenge or become the next victims. Beyond awaits a bewitching land where even the best of their hearts could betray them. Yet, Richard fears nothing so much as what secrets his sword might reveal about his own soul. Falling in love would destroy them - for reasons Richard can't imagine and Kahlan dare not say. In their darkest hour, hunted relentlessly, tormented by treachery and loss, Kahlan calls upon Richard to reach beyond his sword - to invoke within himself something more noble. Neither knows that the rules of battle have just changed...or that their time has run out. Wizard's First Rule is the beginning. One book. One Rule. Witness the birth of a legend.
isbn:
description: The ISBN of the book. Will be null if unknown.
type: string
nullable: true
asin:
description: The ASIN of the book. Will be null if unknown.
type: string
nullable: true
example: B002V0QK4C
language:
description: The language of the book. Will be null if unknown.
type: string
nullable: true
explicit:
description: Whether the book has been marked as explicit.
type: boolean
example: false
abridged:
description: Whether the book is abridged.
type: boolean
example: false
authorMinified:
type: object
description: Minified author object which only contains the author name and ID.
properties:
id:
$ref: '#/components/schemas/authorId'
name:
$ref: '#/components/schemas/authorName'
seriesId:
type: string
description: The ID of the series.
format: uuid
example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
seriesName:
description: The name of the series.
type: string
example: Sword of Truth
sequence:
description: The position in the series the book is.
type: string
nullable: true
seriesSequence:
type: object
description: A series object which includes the name and sequence of the series.
properties:
id:
$ref: '#/components/schemas/seriesId'
name:
$ref: '#/components/schemas/seriesName'
sequence:
$ref: '#/components/schemas/sequence'
bookMetadata:
allOf:
- $ref: '#/components/schemas/bookMetadataBase'
- type: object
properties:
authors:
type: array
items:
$ref: '#/components/schemas/authorMinified'
narrators:
type: array
items:
type: string
example: Sam Tsoutsouvas
series:
type: array
items:
$ref: '#/components/schemas/seriesSequence'
book:
allOf:
- $ref: '#/components/schemas/bookBase'
- type: object
properties:
metadata:
$ref: '#/components/schemas/bookMetadata'
libraryItemBase:
type: object
description: Base library item schema
properties:
id:
$ref: '#/components/schemas/libraryItemId'
oldLibraryItemId:
$ref: '#/components/schemas/oldLibraryItemId'
ino:
$ref: '#/components/schemas/inode'
libraryId:
$ref: '#/components/schemas/libraryId'
folderId:
$ref: '#/components/schemas/folderId'
path:
description: The path of the library item on the server.
type: string
relPath:
description: The path, relative to the library folder, of the library item.
type: string
isFile:
description: Whether the library item is a single file in the root of the library folder.
type: boolean
mtimeMs:
description: The time (in ms since POSIX epoch) when the library item was last modified on disk.
type: integer
ctimeMs:
description: The time (in ms since POSIX epoch) when the library item status was changed on disk.
type: integer
birthtimeMs:
description: The time (in ms since POSIX epoch) when the library item was created on disk. Will be 0 if unknown.
type: integer
addedAt:
$ref: '#/components/schemas/addedAt'
updatedAt:
$ref: '#/components/schemas/updatedAt'
isMissing:
description: Whether the library item was scanned and no longer exists.
type: boolean
isInvalid:
description: Whether the library item was scanned and no longer has media files.
type: boolean
mediaType:
$ref: '#/components/schemas/mediaType'
media:
$ref: '#/components/schemas/book'
bookMetadataMinified:
type: object
description: The minified metadata for a book in the database.
allOf:
- $ref: '#/components/schemas/bookMetadataBase'
- type: object
properties:
titleIgnorePrefix:
description: The title of the book with any prefix moved to the end.
type: string
authorName:
description: The name of the book's author(s).
type: string
example: Terry Goodkind
authorNameLF:
description: The name of the book's author(s) with last names first.
type: string
example: Goodkind, Terry
narratorName:
description: The name of the audiobook's narrator(s).
type: string
example: Sam Tsoutsouvas
seriesName:
description: The name of the book's series.
type: string
example: Sword of Truth
bookMinified:
type: object
description: Minified book schema. Does not depend on `bookBase` because there's pretty much no overlap.
properties:
metadata:
$ref: '#/components/schemas/bookMetadataMinified'
coverPath:
$ref: '#/components/schemas/bookCoverPath'
tags:
$ref: '#/components/schemas/tags'
numTracks:
description: The number of tracks the book's audio files have.
type: integer
example: 1
numAudioFiles:
description: The number of audio files the book has.
type: integer
example: 1
numChapters:
description: The number of chapters the book has.
type: integer
example: 1
numMissingParts:
description: The total number of missing parts the book has.
type: integer
example: 0
numInvalidAudioFiles:
description: The number of invalid audio files the book has.
type: integer
example: 0
duration:
$ref: '#/components/schemas/durationSec'
size:
$ref: '#/components/schemas/size'
ebookFormat:
description: The format of ebook of the book. Will be null if the book is an audiobook.
type: string
nullable: true
mediaMinified:
description: The minified media of the library item.
oneOf:
- $ref: '#/components/schemas/bookMinified'
libraryItemMinified:
type: object
description: A single item on the server, like a book or podcast. Minified media format.
allOf:
- $ref: '#/components/schemas/libraryItemBase'
- type: object
properties:
media:
$ref: '#/components/schemas/mediaMinified'
authorSeries:
type: object
description: Series and the included library items that an author has written.
properties:
id:
$ref: '#/components/schemas/seriesId'
name:
$ref: '#/components/schemas/seriesName'
items:
description: The items in the series. Each library item's media's metadata will have a `series` attribute, a `Series Sequence`, which is the matching series.
type: array
items:
$ref: '#/components/schemas/libraryItemMinified'
author:
description: An author object which includes a description and image path. The library items and series associated with the author are optionally included.
type: object
properties:
id:
$ref: '#/components/schemas/authorId'
asin:
$ref: '#/components/schemas/authorAsin'
name:
$ref: '#/components/schemas/authorName'
description:
$ref: '#/components/schemas/authorDescription'
imagePath:
$ref: '#/components/schemas/authorImagePath'
addedAt:
$ref: '#/components/schemas/addedAt'
updatedAt:
$ref: '#/components/schemas/updatedAt'
libraryItems:
description: The items associated with the author
type: array
items:
$ref: '#/components/schemas/libraryItemMinified'
series:
description: The series associated with the author
type: array
items:
$ref: '#/components/schemas/authorSeries'
authorUpdated:
description: Whether the author was updated without errors. Will not exist if author was merged.
type: boolean
nullable: true
authorMerged:
description: Whether the author was merged with another author. Will not exist if author was updated.
type: boolean
nullable: true
imageWidth:
description: The requested width of image in pixels.
type: integer
default: 400
example: 400
imageHeight:
description: The requested height of image in pixels. If `null`, the height is scaled to maintain aspect ratio based on the requested width.
type: integer
nullable: true
default: null
example: 600
imageFormat:
description: The requested output format.
type: string
default: jpeg
example: webp
imageRaw:
description: Return the raw image without scaling if true.
type: boolean
default: false
imageUrl:
description: The URL of the image to add to the server
type: string
format: uri
example: https://images-na.ssl-images-amazon.com/images/I/51NoQTm33OL.__01_SX120_CR0,0,120,120__.jpg
authorSearchName:
description: The name of the author to use for searching.
type: string
example: Terry Goodkind
region:
description: The region used to search.
type: string
example: us
default: us
ereaderName:
type: string
description: The name of the e-reader device.
EreaderDeviceObject:
type: object
description: An e-reader device configured to receive EPUB through e-mail.
properties:
name:
$ref: '#/components/schemas/ereaderName'
email:
type: string
description: The email address associated with the e-reader device.
availabilityOption:
type: string
description: The availability option for the device.
enum:
- adminOrUp
- userOrUp
- guestOrUp
- specificUsers
users:
type: array
description: List of specific users allowed to access the device.
items:
type: string
required:
- name
- email
- availabilityOption
EmailSettings:
type: object
description: The email settings configuration for the server. This includes the credentials to send e-books and an array of e-reader devices.
properties:
id:
type: string
description: The unique identifier for the email settings. Currently this is always `email-settings`
example: email-settings
host:
type: string
description: The SMTP host address.
nullable: true
port:
type: integer
format: int32
description: The port number for the SMTP server.
example: 465
secure:
type: boolean
description: Indicates if the connection should use SSL/TLS.
example: true
rejectUnauthorized:
type: boolean
description: Indicates if unauthorized SSL/TLS certificates should be rejected.
example: true
user:
type: string
description: The username for SMTP authentication.
nullable: true
pass:
type: string
description: The password for SMTP authentication.
nullable: true
testAddress:
type: string
description: The test email address used for sending test emails.
nullable: true
fromAddress:
type: string
description: The default "from" email address for outgoing emails.
nullable: true
ereaderDevices:
type: array
description: List of configured e-reader devices.
items:
$ref: '#/components/schemas/EreaderDeviceObject'
required:
- id
- port
- secure
- ereaderDevices
libraryName:
description: The name of the library.
type: string
example: My Audiobooks
folder:
type: object
description: Folder used in library
properties:
id:
$ref: '#/components/schemas/folderId'
fullPath:
description: The path on the server for the folder. (Read Only)
type: string
example: /podcasts
libraryId:
$ref: '#/components/schemas/libraryId'
addedAt:
$ref: '#/components/schemas/addedAt'
librarySettings:
description: The settings for the library.
type: object
properties:
coverAspectRatio:
description: Whether the library should use square book covers. Must be 0 (for false) or 1 (for true).
type: integer
example: 1
disableWatcher:
description: Whether to disable the folder watcher for the library.
type: boolean
example: false
skipMatchingMediaWithAsin:
description: Whether to skip matching books that already have an ASIN.
type: boolean
example: false
skipMatchingMediaWithIsbn:
description: Whether to skip matching books that already have an ISBN.
type: boolean
example: false
autoScanCronExpression:
description: The cron expression for when to automatically scan the library folders. If null, automatic scanning will be disabled.
type: string
nullable: true
example: 0 0 0 * * *
audiobooksOnly:
description: Whether the library should ignore ebook files and only allow ebook files to be supplementary.
type: boolean
example: false
hideSingleBookSeries:
description: Whether to hide series with only one book.
type: boolean
example: false
onlyShowLaterBooksInContinueSeries:
description: Whether to only show books in a series after the highest series sequence.
type: boolean
example: false
metadataPrecedence:
description: The precedence of metadata sources. See Metadata Providers for a list of possible providers.
type: array
items:
type: string
example:
- folderStructure
- audioMetatags
- nfoFile
- txtFiles
- opfFile
- absMetadata
podcastSearchRegion:
description: The region to use when searching for podcasts.
type: string
example: us
createdAt:
type: integer
description: The time (in ms since POSIX epoch) when was created.
example: 1633522963509
library:
description: A library object which includes either books or podcasts.
type: object
properties:
id:
$ref: '#/components/schemas/libraryId'
name:
$ref: '#/components/schemas/libraryName'
folders:
description: The folders that belong to the library.
type: array
items:
$ref: '#/components/schemas/folder'
displayOrder:
description: Display position of the library in the list of libraries. Must be >= 1.
type: integer
example: 1
icon:
description: The selected icon for the library. See Library Icons for a list of possible icons.
type: string
example: audiobookshelf
mediaType:
description: The type of media that the library contains. Will be `book` or `podcast`. (Read Only)
type: string
example: book
provider:
description: Preferred metadata provider for the library. See Metadata Providers for a list of possible providers.
type: string
example: audible
settings:
$ref: '#/components/schemas/librarySettings'
createdAt:
$ref: '#/components/schemas/createdAt'
lastUpdate:
$ref: '#/components/schemas/updatedAt'
libraryFolders:
description: The folders of the library. Only specify the fullPath.
type: array
items:
$ref: '#/components/schemas/folder'
libraryDisplayOrder:
description: The display order of the library. Must be >= 1.
type: integer
minimum: 1
example: 1
libraryIcon:
description: The icon of the library. See Library Icons for a list of possible icons.
type: string
example: audiobookshelf
libraryMediaType:
description: The type of media that the library contains. Must be `book` or `podcast`.
type: string
example: book
libraryProvider:
description: Preferred metadata provider for the library. See Metadata Providers for a list of possible providers.
type: string
example: audible
authorExpanded:
type: object
description: The author schema with the total number of books in the library.
allOf:
- $ref: '#/components/schemas/author'
- type: object
properties:
numBooks:
description: The number of books associated with the author in the library.
type: integer
example: 1
total:
description: The total number of items in the response.
type: integer
example: 100
limit:
description: The number of items to return. If 0, no items are returned.
type: integer
example: 10
default: 0
page:
description: The page number (zero indexed) to return. If no limit is specified, then page will have no effect.
type: integer
example: 1
default: 0
sortBy:
type: string
description: The field to sort by from the request.
example: media.metadata.title
sortDesc:
description: Whether to sort in descending order.
type: boolean
example: true
filterBy:
type: string
description: The field to filter by from the request. TODO
example: media.metadata.title
minified:
description: Return minified items if true.
type: boolean
example: true
default: false
collapseSeries:
type: boolean
description: Whether collapse series was set in the request.
example: true
libraryInclude:
description: The fields to include in the response. The only current option is `rssfeed`.
type: string
example: rssfeed
libraryItemSequence:
type: object
description: A single item on the server, like a book or podcast. Includes series sequence information.
allOf:
- $ref: '#/components/schemas/libraryItemBase'
- type: object
properties:
sequence:
$ref: '#/components/schemas/sequence'
seriesBooks:
type: object
description: A series object which includes the name and books in the series.
properties:
id:
$ref: '#/components/schemas/seriesId'
name:
$ref: '#/components/schemas/seriesName'
addedAt:
$ref: '#/components/schemas/addedAt'
nameIgnorePrefix:
description: The name of the series with any prefix moved to the end.
type: string
nameIgnorePrefixSort:
description: The name of the series with any prefix removed.
type: string
type:
description: Will always be `series`.
type: string
books:
description: The library items that contain the books in the series. A sequence attribute that denotes the position in the series the book is in, is tacked on.
type: array
items:
$ref: '#/components/schemas/libraryItemSequence'
totalDuration:
description: The combined duration (in seconds) of all books in the series.
type: number
seriesDescription:
description: A description for the series. Will be null if there is none.
type: string
nullable: true
example: The Sword of Truth is a series of twenty one epic fantasy novels written by Terry Goodkind.
series:
type: object
description: A series object which includes the name and description of the series.
properties:
id:
$ref: '#/components/schemas/seriesId'
name:
$ref: '#/components/schemas/seriesName'
description:
$ref: '#/components/schemas/seriesDescription'
addedAt:
$ref: '#/components/schemas/addedAt'
updatedAt:
$ref: '#/components/schemas/updatedAt'
seriesProgress:
type: object
description: The user's progress of a series.
properties:
libraryItemIds:
description: The IDs of the library items in the series.
type: array
items:
$ref: '#/components/schemas/libraryItemId'
libraryItemIdsFinished:
description: The IDs of the library items in the series that are finished.
type: array
items:
$ref: '#/components/schemas/libraryItemId'
isFinished:
description: Whether the series is finished.
type: boolean
seriesWithProgressAndRSS:
type: object
description: A series object which includes the name and progress of the series.
oneOf:
- $ref: '#/components/schemas/series'
- type: object
properties:
progress:
$ref: '#/components/schemas/seriesProgress'
rssFeed:
description: The RSS feed for the series.
type: string
example: TBD
NotificationEvent:
type: object
properties:
name:
type: string
description: The name of the notification event. The names and allowable values are defined at https://github.com/advplyr/audiobookshelf/blob/master/server/utils/notifications.js
requiresLibrary:
type: boolean
description: Whether the notification event depends on a library existing.
libraryMediaType:
type: string
description: The type of media of the library the notification depends on existing. Will not exist if requiresLibrary is false.
nullable: true
description:
type: string
description: The description of the notification event.
variables:
type: array
items:
type: string
description: The variables of the notification event that can be used in the notification templates.
defaults:
type: object
properties:
title:
type: string
description: The default title template for notifications using the notification event.
body:
type: string
description: The default body template for notifications using the notification event.
testData:
type: object
description: The keys of the testData object will match the list of variables. The values will be the data used when sending a test notification.
additionalProperties:
type: string
notificationId:
type: string
description: The ID of the notification.
example: notification-settings
appriseApiUrl:
type: string
nullable: true
description: The full URL where the Apprise API to use is located.
libraryIdNullable:
type: string
description: The ID of the library. Applies to all libraries if `null`.
format: uuid
nullable: true
example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
notificationEventName:
type: string
description: The name of the event the notification will fire on.
enum:
- onPodcastEpisodeDownloaded
- onTest
urls:
type: array
items:
type: string
description: The Apprise URLs to use for the notification.
example: http://192.168.0.3:8000/notify/my-cool-notification
titleTemplate:
type: string
description: The template for the notification title.
example: New {{podcastTitle}} Episode!
bodyTemplate:
type: string
description: The template for the notification body.
example: '{{episodeTitle}} has been added to {{libraryName}} library.'
enabled:
type: boolean
default: false
description: Whether the notification is enabled.
notificationType:
type: string
enum:
- info
- success
- warning
- failure
nullable: true
default: info
description: The notification's type.
Notification:
type: object
properties:
id:
$ref: '#/components/schemas/notificationId'
libraryId:
$ref: '#/components/schemas/libraryIdNullable'
eventName:
$ref: '#/components/schemas/notificationEventName'
urls:
$ref: '#/components/schemas/urls'
titleTemplate:
$ref: '#/components/schemas/titleTemplate'
bodyTemplate:
$ref: '#/components/schemas/bodyTemplate'
enabled:
$ref: '#/components/schemas/enabled'
type:
$ref: '#/components/schemas/notificationType'
lastFiredAt:
type: integer
nullable: true
description: The time (in ms since POSIX epoch) when the notification was last fired. Will be null if the notification has not fired.
lastAttemptFailed:
type: boolean
description: Whether the last notification attempt failed.
numConsecutiveFailedAttempts:
type: integer
description: The number of consecutive times the notification has failed.
default: 0
numTimesFired:
type: integer
description: The number of times the notification has fired.
default: 0
createdAt:
$ref: '#/components/schemas/createdAt'
maxFailedAttempts:
type: integer
minimum: 0
default: 5
description: The maximum number of times a notification fails before being disabled.
maxNotificationQueue:
type: integer
description: The maximum number of notifications in the notification queue before events are ignored.
NotificationSettings:
type: object
properties:
id:
$ref: '#/components/schemas/notificationId'
appriseType:
type: string
description: The type of Apprise that will be used. At the moment, only api is available.
appriseApiUrl:
$ref: '#/components/schemas/appriseApiUrl'
notifications:
type: array
items:
$ref: '#/components/schemas/Notification'
description: The set notifications.
maxFailedAttempts:
$ref: '#/components/schemas/maxFailedAttempts'
maxNotificationQueue:
$ref: '#/components/schemas/maxNotificationQueue'
notificationDelay:
type: integer
description: The time (in ms) between notification pushes.
podcastId:
type: string
description: The ID of podcasts and podcast episodes after 2.3.0.
format: uuid
example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
PodcastMetadata:
type: object
description: Metadata for a podcast.
properties:
title:
type: string
description: The title of the podcast.
nullable: true
author:
type: string
description: The author of the podcast.
nullable: true
description:
type: string
description: The description of the podcast.
nullable: true
releaseDate:
type: string
format: date-time
description: The release date of the podcast.
nullable: true
genres:
type: array
description: The genres of the podcast.
items:
type: string
feedUrl:
type: string
description: The URL of the podcast feed.
nullable: true
imageUrl:
type: string
description: The URL of the podcast's image.
nullable: true
itunesPageUrl:
type: string
description: The URL of the podcast's iTunes page.
nullable: true
itunesId:
type: string
description: The iTunes ID of the podcast.
nullable: true
itunesArtistId:
type: string
description: The iTunes artist ID of the podcast.
nullable: true
explicit:
type: boolean
description: Whether the podcast contains explicit content.
language:
type: string
description: The language of the podcast.
nullable: true
type:
type: string
description: The type of podcast (e.g., episodic, serial).
nullable: true
oldPodcastId:
description: The ID of podcasts on server version 2.2.23 and before.
type: string
nullable: true
format: pod_[a-z0-9]{18}
example: pod_o78uaoeuh78h6aoeif
AudioTrack:
type: object
description: Represents an audio track with various properties.
properties:
index:
type: integer
nullable: true
description: The index of the audio track.
example: null
startOffset:
type: number
format: float
nullable: true
description: The start offset of the audio track in seconds.
example: null
duration:
type: number
format: float
nullable: true
description: The duration of the audio track in seconds.
example: null
title:
type: string
nullable: true
description: The title of the audio track.
example: null
contentUrl:
type: string
nullable: true
description: The URL where the audio track content is located.
example: '`/api/items/${itemId}/file/${audioFile.ino}`'
mimeType:
type: string
nullable: true
description: The MIME type of the audio track.
example: null
codec:
type: string
nullable: true
description: The codec used for the audio track.
example: aac
metadata:
$ref: '#/components/schemas/fileMetadata'
PodcastEpisode:
type: object
description: A single episode of a podcast.
properties:
libraryItemId:
$ref: '#/components/schemas/libraryItemId'
podcastId:
$ref: '#/components/schemas/podcastId'
id:
$ref: '#/components/schemas/podcastId'
oldEpisodeId:
$ref: '#/components/schemas/oldPodcastId'
index:
type: integer
description: The index of the episode within the podcast.
nullable: true
season:
type: string
description: The season number of the episode.
nullable: true
episode:
type: string
description: The episode number within the season.
nullable: true
episodeType:
type: string
description: The type of episode (e.g., full, trailer).
nullable: true
title:
type: string
description: The title of the episode.
nullable: true
subtitle:
type: string
description: The subtitle of the episode.
nullable: true
description:
type: string
description: The description of the episode.
nullable: true
enclosure:
type: object
description: The enclosure object containing additional episode data.
nullable: true
additionalProperties: true
guid:
type: string
description: The globally unique identifier for the episode.
nullable: true
pubDate:
type: string
description: The publication date of the episode.
nullable: true
chapters:
type: array
description: The chapters within the episode.
items:
type: object
audioFile:
$ref: '#/components/schemas/audioFile'
publishedAt:
$ref: '#/components/schemas/createdAt'
addedAt:
$ref: '#/components/schemas/addedAt'
updatedAt:
$ref: '#/components/schemas/updatedAt'
audioTrack:
$ref: '#/components/schemas/AudioTrack'
duration:
$ref: '#/components/schemas/durationSec'
size:
$ref: '#/components/schemas/size'
autoDownloadEpisodes:
type: boolean
description: Whether episodes are automatically downloaded.
Podcast:
type: object
description: A podcast containing multiple episodes.
properties:
id:
$ref: '#/components/schemas/podcastId'
libraryItemId:
$ref: '#/components/schemas/libraryItemId'
metadata:
$ref: '#/components/schemas/PodcastMetadata'
coverPath:
type: string
description: The file path to the podcast's cover image.
nullable: true
tags:
type: array
description: The tags associated with the podcast.
items:
type: string
episodes:
type: array
description: The episodes of the podcast.
items:
$ref: '#/components/schemas/PodcastEpisode'
autoDownloadEpisodes:
$ref: '#/components/schemas/autoDownloadEpisodes'
autoDownloadSchedule:
type: string
description: The schedule for automatic episode downloads, in cron format.
nullable: true
lastEpisodeCheck:
type: integer
description: The timestamp of the last episode check.
maxEpisodesToKeep:
type: integer
description: The maximum number of episodes to keep.
maxNewEpisodesToDownload:
type: integer
description: The maximum number of new episodes to download when automatically downloading epsiodes.
lastCoverSearch:
type: integer
description: The timestamp of the last cover search.
nullable: true
lastCoverSearchQuery:
type: string
description: The query used for the last cover search.
nullable: true
size:
type: integer
description: The total size of all episodes in bytes.
duration:
type: integer
description: The total duration of all episodes in seconds.
numTracks:
type: integer
description: The number of tracks (episodes) in the podcast.
latestEpisodePublished:
type: integer
description: The timestamp of the most recently published episode.
username:
type: string
description: The username to log in with.
example: testuser
password:
type: string
description: The password of the user.
example: password
userId:
type: string
description: The ID of the user.
example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
format: uuid
userType:
type: string
description: The type of the user.
example: root
token:
type: string
description: The token of the user.
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InRlc3R1c2VyIiwiaWF0IjoxNTE2MjM5MDIyfQ.4k1jJ9
mediaProgressId:
type: string
description: The ID of the media progress.
example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
format: uuid
progress:
type: number
description: The user's progress in the media item.
example: 0.5
currentTime:
type: number
description: The user's current time in the media item.
example: 0.5
isFinished:
type: boolean
description: Whether the user has finished the media item.
example: false
hideFromContinueListening:
type: boolean
description: Whether the media item should be hidden from the continue listening section.
example: false
finishedAt:
type: integer
nullable: true
description: The time (in ms since POSIX epoch) when the media was finished. Will be null if the media has is not finished.
example: 1616239000
mediaProgress:
type: object
properties:
id:
$ref: '#/components/schemas/mediaProgressId'
libraryItemId:
$ref: '#/components/schemas/libraryItemId'
duration:
$ref: '#/components/schemas/durationSec'
progress:
$ref: '#/components/schemas/progress'
currentTime:
$ref: '#/components/schemas/currentTime'
isFinished:
$ref: '#/components/schemas/isFinished'
hideFromContinueListening:
$ref: '#/components/schemas/hideFromContinueListening'
lastUpdate:
$ref: '#/components/schemas/updatedAt'
startedAt:
$ref: '#/components/schemas/createdAt'
finishedAt:
$ref: '#/components/schemas/finishedAt'
time:
type: integer
description: The time (in ms since POSIX epoch) when the bookmark was created.
example: 1616239000
bookmark:
properties:
libraryItemId:
$ref: '#/components/schemas/libraryItemId'
title:
type: string
description: The title of the bookmark.
example: Chapter 1
time:
$ref: '#/components/schemas/time'
createdAt:
$ref: '#/components/schemas/createdAt'
lastSeen:
type: integer
description: The time (in ms since POSIX epoch) when the user was last seen.
example: 1616239000
isActive:
type: boolean
description: Whether the user is active.
example: true
isLocked:
type: boolean
description: Whether the user is locked.
example: false
download:
type: boolean
description: Whether the user has permission to download media.
example: true
update:
type: boolean
description: Whether the user has permission to update media.
example: true
delete:
type: boolean
description: Whether the user has permission to delete media.
example: true
upload:
type: boolean
description: Whether the user has permission to upload media.
example: true
accessAllLibraries:
type: boolean
description: Whether the user has permission to access all libraries.
example: true
accessAllTags:
type: boolean
description: Whether the user has permission to access all tags.
example: true
accessExplicitContent:
type: boolean
description: Whether the user has permission to access explicit content.
example: true
permissions:
type: object
properties:
download:
$ref: '#/components/schemas/download'
update:
$ref: '#/components/schemas/update'
delete:
$ref: '#/components/schemas/delete'
upload:
$ref: '#/components/schemas/upload'
accessAllLibraries:
$ref: '#/components/schemas/accessAllLibraries'
accessAllTags:
$ref: '#/components/schemas/accessAllTags'
accessExplicitContent:
$ref: '#/components/schemas/accessExplicitContent'
required:
- download
- update
- delete
- upload
- accessAllLibraries
- accessAllTags
- accessExplicitContent
user:
type: object
description: A user object which includes the user's ID, username, type, token, and media progress.
properties:
id:
$ref: '#/components/schemas/userId'
username:
$ref: '#/components/schemas/username'
type:
$ref: '#/components/schemas/userType'
token:
$ref: '#/components/schemas/token'
mediaProgress:
description: The user's progress of media.
type: array
items:
$ref: '#/components/schemas/mediaProgress'
seriesHideFromContinueListening:
description: The IDs of series to hide from the user's "Continue Series" shelf.
type: array
items:
$ref: '#/components/schemas/libraryItemId'
bookmarks:
description: The user's bookmarks.
type: array
items:
$ref: '#/components/schemas/bookmark'
lastSeen:
$ref: '#/components/schemas/lastSeen'
isActive:
$ref: '#/components/schemas/isActive'
isLocked:
$ref: '#/components/schemas/isLocked'
createdAt:
$ref: '#/components/schemas/createdAt'
permissions:
$ref: '#/components/schemas/permissions'
librariesAccessible:
description: The IDs of libraries the user has access to.
type: array
items:
$ref: '#/components/schemas/libraryId'
itemTagsSelected:
$ref: '#/components/schemas/tags'
socketId:
type: string
description: The socket ID of the user.
example: AFcTcb7xBLsSPnIzAAAV
libraryFile:
type: object
description: A library file. Includes the path and metadata of the file.
properties:
ino:
$ref: '#/components/schemas/inode'
addedAt:
$ref: '#/components/schemas/addedAt'
updatedAt:
$ref: '#/components/schemas/updatedAt'
fileType:
description: The type of file.
type: string
example: audio
metadata:
$ref: '#/components/schemas/fileMetadata'
libraryItem:
type: object
description: A single item on the server, like a book or podcast.
allOf:
- $ref: '#/components/schemas/libraryItemBase'
- type: object
properties:
libraryFiles:
type: array
items:
$ref: '#/components/schemas/libraryFile'
deviceId:
description: The client device identifier.
type: string
example: 1
clientVersion:
description: The client version.
type: string
example: 1.0.0
clientName:
description: The client name.
type: string
example: Audible
manufacturer:
description: The manufacturer of the device.
type: string
example: Apple
model:
description: The model of the device.
type: string
example: iPhone 12
sdkVersion:
description: For an Android client, the Android SDK version of the client.
type: string
example: 49
deviceInfo:
description: The device information to send to the server.
type: object
properties:
deviceId:
$ref: '#/components/schemas/deviceId'
clientVersion:
$ref: '#/components/schemas/clientVersion'
clientName:
$ref: '#/components/schemas/clientName'
manufacturer:
$ref: '#/components/schemas/manufacturer'
model:
$ref: '#/components/schemas/model'
sdkVersion:
$ref: '#/components/schemas/sdkVersion'
forceDirectPlay:
description: Whether to force direct play of the library item.
type: boolean
example: false
forceTranscode:
description: Whether to force transcoding of the library item.
type: boolean
example: false
supportedMimeTypes:
description: The supported mime types for the device.
type: array
items:
type: string
mediaPlayer:
description: The media player to use.
type: string
playbackSessionId:
description: The playback session identifier.
type: string
format: uuid
serverVersion:
type: string
description: The server version
playbackSessionBase:
type: object
description: Base playback session object.
properties:
id:
$ref: '#/components/schemas/playbackSessionId'
userId:
$ref: '#/components/schemas/userId'
libraryId:
$ref: '#/components/schemas/libraryId'
libraryItemId:
$ref: '#/components/schemas/libraryItemId'
mediaType:
$ref: '#/components/schemas/mediaType'
displayTitle:
description: The display title of the media.
type: string
displayAuthor:
description: The display author of the media.
type: string
coverPath:
$ref: '#/components/schemas/bookCoverPath'
duration:
$ref: '#/components/schemas/durationSec'
playMethod:
type: integer
description: The method used to play the media. 0 = Direct play, 1 = Direct Stream, 2 = Transcode, 3 = Local
mediaPlayer:
type: string
description: The media player used to play the media.
deviceInfo:
$ref: '#/components/schemas/deviceInfo'
serverVersion:
$ref: '#/components/schemas/serverVersion'
date:
description: TODO
type: string
dayOfWeek:
description: TODO
type: string
timeListening:
$ref: '#/components/schemas/durationSec'
startTime:
$ref: '#/components/schemas/durationSec'
currentTime:
$ref: '#/components/schemas/durationSec'
createdAt:
$ref: '#/components/schemas/createdAt'
updatedAt:
$ref: '#/components/schemas/updatedAt'
playbackSessionBook:
description: Book playback session schema.
allOf:
- $ref: '#/components/schemas/playbackSessionBase'
- properties:
mediaMetadata:
$ref: '#/components/schemas/bookMetadata'
chapters:
description: The chapters of the media.
type: array
items:
$ref: '#/components/schemas/bookChapter'
playbackSessionBookExpanded:
description: Expanded book playback session schema.
allOf:
- $ref: '#/components/schemas/playbackSessionBook'
- properties:
audioTracks:
description: The audio tracks of the media.
type: array
items:
$ref: '#/components/schemas/AudioTrack'
videoTrack:
description: The video track of the media. TODO
type: object
nullable: true
libraryItem:
$ref: '#/components/schemas/libraryItem'
playbackSessionPodcast:
description: Podcast playback session schema.
allOf:
- $ref: '#/components/schemas/playbackSessionBase'
- properties:
mediaMetadata:
$ref: '#/components/schemas/PodcastMetadata'
episodeId:
$ref: '#/components/schemas/podcastId'
playbackSessionPodcastExpanded:
description: Expanded podcast playback session schema.
allOf:
- $ref: '#/components/schemas/playbackSessionPodcast'
- properties:
audioTracks:
description: The audio tracks of the media.
type: array
items:
$ref: '#/components/schemas/AudioTrack'
videoTrack:
description: The video track of the media. TODO
type: object
nullable: true
libraryItem:
$ref: '#/components/schemas/libraryItem'
playbackSessionExpanded:
type: object
description: A playback session object.
oneOf:
- $ref: '#/components/schemas/playbackSessionBookExpanded'
- $ref: '#/components/schemas/playbackSessionPodcastExpanded'
discriminator:
propertyName: mediaType
mapping:
book: '#/components/schemas/playbackSessionBookExpanded'
podcast: '#/components/schemas/playbackSessionPodcastExpanded'
mediaProgressPodcastEpisode:
type: object
properties:
id:
$ref: '#/components/schemas/mediaProgressId'
libraryItemId:
$ref: '#/components/schemas/libraryItemId'
episodeId:
$ref: '#/components/schemas/podcastId'
duration:
$ref: '#/components/schemas/durationSec'
progress:
$ref: '#/components/schemas/progress'
currentTime:
$ref: '#/components/schemas/currentTime'
isFinished:
$ref: '#/components/schemas/isFinished'
hideFromContinueListening:
$ref: '#/components/schemas/hideFromContinueListening'
lastUpdate:
$ref: '#/components/schemas/updatedAt'
startedAt:
$ref: '#/components/schemas/createdAt'
finishedAt:
$ref: '#/components/schemas/finishedAt'
playbackSession:
type: object
description: A playback session object.
oneOf:
- $ref: '#/components/schemas/playbackSessionBook'
- $ref: '#/components/schemas/playbackSessionPodcast'
discriminator:
propertyName: mediaType
mapping:
book: '#/components/schemas/playbackSessionBook'
podcast: '#/components/schemas/playbackSessionPodcast'
totalTime:
description: The total time listened in seconds.
type: number
example: 123456
responses:
author404:
description: Author not found.
content:
text/html:
schema:
type: string
example: Author not found.
email200:
description: Successful response - Email
content:
application/json:
schema:
$ref: '#/components/schemas/EmailSettings'
ereader200:
description: Successful response - Ereader
content:
application/json:
schema:
type: object
properties:
ereaderDevices:
type: array
items:
$ref: '#/components/schemas/EreaderDeviceObject'
library200:
description: Library found.
content:
application/json:
schema:
$ref: '#/components/schemas/library'
library404:
description: Library not found.
content:
text/html:
schema:
type: string
example: Library not found.
notification404:
description: An admin user is required or notification with the given ID not found.
content:
text/html:
schema:
type: string
example: Series not found.
notification200:
description: Notification endpoint success.
content:
text/html:
schema:
type: string
example: OK
series404:
description: Series not found.
content:
text/html:
schema:
type: string
example: Series not found.
libraryItem404:
description: Not Found
content:
text/html:
schema:
type: string
description: The library item does not exist.
example: Not Found
me404:
description: Not Found
content:
html/text:
schema:
type: string
example: Not Found
parameters:
minified:
in: query
name: minified
description: Return minified items if true
schema:
type: integer
minimum: 0
example: 1
limit:
in: query
name: limit
description: The number of items to return. This the size of a single page for the optional `page` query.
example: 10
schema:
type: integer
default: 0
page:
in: query
name: page
description: The page number (zero indexed) to return. If no limit is specified, then page will have no effect.
example: 0
schema:
type: integer
default: 0
desc:
in: query
name: desc
description: Return items in reversed order if true.
example: 0
schema:
type: integer
default: 0
include:
in: query
name: include
description: A comma separated list of what to include with the library item. The options are progress, rssfeed, authors (for books), and downloads (for podcasts). expanded must be 1 for include to have an effect.
allowReserved: true
schema:
type: string
expanded:
in: query
name: expanded
description: Whether to return Library Item Expanded instead. 0 for false, 1 for true.
schema:
type: integer
example: 1
episode:
in: query
name: episode
description: If requesting progress for a podcast, the episode ID to get progress for.
schema:
$ref: '#/components/schemas/podcastId'
Reference in a new issue View git blame Copy permalink