{ "openapi": "3.0.3", "info": { "title": "Ampache REST API (v6)", "version": "6.9.2", "description": "OpenAPI 3.0 specification for the Ampache REST API, pinned to API version 6. API6 is served by both Ampache7 and Ampache8 and describes only the surface both honour: the API8-only paths (/folder, /folders, /playlists/{playlist_id}/remove) are absent, as is /random (served by API6 on Ampache8 but not Ampache7). Unlike API version 8, API versions 3-6 always return HTTP 200 and carry any error in the response body, so only success responses are documented. Response schemas come from the Json6_Data builders. Maintained by hand and guarded by tests/Module/Api/Api6SpecConformanceTest.php, which fails if the running code drifts from this document. advanced_search/search with type=album_disk is not documented here: album disks have no API6 formatter, so API6 returns an empty result for that type rather than the song-shaped rows it used to emit. Album disks are API8 only.", "license": { "name": "AGPL-3.0", "url": "https://www.gnu.org/licenses/agpl-3.0.html" } }, "servers": [ { "url": "{ampacheUrl}/rest/{apiVersion}/{format}", "variables": { "ampacheUrl": { "default": "https://develop.ampache.dev", "description": "Base URL to your Ampache Server." }, "apiVersion": { "enum": [ "6" ], "default": "6", "description": "Ampache API major version" }, "format": { "enum": [ "json", "xml" ], "default": "json", "description": "Response format. JSON and XML calls are the same, only the response differs." } } } ], "tags": [ { "name": "Authentication", "description": "Authentication, session management, registration and health endpoints" }, { "name": "Albums", "description": "Album browsing, lookup and album-related metadata" }, { "name": "Artists", "description": "Artist browsing, artist details and related albums or songs" }, { "name": "Songs", "description": "Song browsing, song metadata, lyrics, scrobbling and play history" }, { "name": "Playlists", "description": "Playlist creation, editing, deletion and playlist item management" }, { "name": "Bookmarks", "description": "Bookmark creation, editing and lookup for media items" }, { "name": "Search", "description": "Search endpoints and search rule discovery" }, { "name": "Catalogs", "description": "Catalog management, scanning and catalog maintenance tasks" }, { "name": "Genres", "description": "Genre browsing and genre-related albums, artists and songs" }, { "name": "Labels", "description": "Label browsing and label-related artists" }, { "name": "Licenses", "description": "License browsing and license-related songs" }, { "name": "Browsing, Indexes and Lists", "description": "Folder-style browsing index and list-style lookup endpoints" }, { "name": "Streaming and Downloads", "description": "Media streaming and download endpoints" }, { "name": "Artwork", "description": "Artwork retrieval and artwork update endpoints" }, { "name": "Videos", "description": "Video browsing and video metadata" }, { "name": "Podcasts", "description": "Podcast management and podcast episode endpoints" }, { "name": "Live Streams", "description": "Live stream (radio) creation, editing and browsing" }, { "name": "Shares", "description": "Public share creation, editing and deletion" }, { "name": "Social", "description": "Followers, following, timelines and social interactions" }, { "name": "Now Playing", "description": "Playback state, now playing and player updates" }, { "name": "Users", "description": "Administrative user management and user-scoped listings" }, { "name": "Preferences", "description": "Server and user preference management" }, { "name": "Maintenance", "description": "Deleted content and system maintenance endpoints" }, { "name": "Ratings and Flags", "description": "Rating, favouriting and flagging of media items" }, { "name": "Playback Control", "description": "Localplay and democratic playback control endpoints" }, { "name": "Utilities", "description": "Helper and utility endpoints such as metadata lookup and URL conversion" } ], "components": { "securitySchemes": { "ApiKeyAuthQuery": { "type": "apiKey", "in": "query", "name": "auth", "description": "Ampache session token or encrypted API key passed as the auth query parameter." }, "ApiKeyAuthHeader": { "type": "apiKey", "in": "header", "name": "auth", "description": "Ampache auth value supplied via HTTP header authentication (as documented for the auth parameter)." }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "opaque", "description": "Bearer token authentication. Ampache supports Bearer Token usage for handshake and ping." } }, "schemas": { "AlbumObject": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "prefix": { "type": "string", "nullable": true }, "basename": { "type": "string", "nullable": true }, "artist": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "prefix": { "type": "string", "nullable": true }, "basename": { "type": "string", "nullable": true } }, "required": [ "id", "name", "prefix", "basename" ], "additionalProperties": false, "nullable": true }, "artists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "prefix": { "type": "string", "nullable": true }, "basename": { "type": "string", "nullable": true } }, "required": [ "id", "name", "prefix", "basename" ], "additionalProperties": false } }, "songartists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "prefix": { "type": "string", "nullable": true }, "basename": { "type": "string", "nullable": true } }, "required": [ "id", "name", "prefix", "basename" ], "additionalProperties": false } }, "time": { "type": "integer" }, "year": { "type": "integer" }, "tracks": { "type": "array", "items": { "$ref": "#/components/schemas/SongObject" } }, "songcount": { "type": "integer" }, "diskcount": { "type": "integer" }, "type": { "type": "string", "nullable": true }, "genre": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "art": { "type": "string", "nullable": true }, "has_art": { "type": "boolean" }, "flag": { "type": "boolean" }, "rating": { "type": "integer", "nullable": true }, "averagerating": { "type": "number", "nullable": true }, "mbid": { "type": "string", "nullable": true }, "mbid_group": { "type": "string", "nullable": true } }, "required": [ "id", "name", "prefix", "basename", "time", "year", "tracks", "songcount", "diskcount", "type", "genre", "art", "has_art", "flag", "rating", "averagerating", "mbid", "mbid_group" ], "additionalProperties": false }, "AlbumsResponse": { "type": "object", "properties": { "total_count": { "type": "integer" }, "md5": { "type": "string" }, "album": { "type": "array", "items": { "$ref": "#/components/schemas/AlbumObject" } } }, "required": [ "total_count", "md5", "album" ], "additionalProperties": false }, "ArtistObject": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "prefix": { "type": "string", "nullable": true }, "basename": { "type": "string", "nullable": true }, "albums": { "type": "array", "items": { "$ref": "#/components/schemas/AlbumObject" } }, "albumcount": { "type": "integer" }, "songs": { "type": "array", "items": { "$ref": "#/components/schemas/SongObject" } }, "songcount": { "type": "integer" }, "genre": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "art": { "type": "string", "nullable": true }, "has_art": { "type": "boolean" }, "flag": { "type": "boolean" }, "rating": { "type": "integer", "nullable": true }, "averagerating": { "type": "number", "nullable": true }, "mbid": { "type": "string", "nullable": true }, "summary": { "type": "string", "nullable": true }, "time": { "type": "integer" }, "yearformed": { "type": "integer" }, "placeformed": { "type": "string", "nullable": true } }, "required": [ "id", "name", "prefix", "basename", "albums", "albumcount", "songs", "songcount", "genre", "art", "has_art", "flag", "rating", "averagerating", "mbid", "summary", "time", "yearformed", "placeformed" ], "additionalProperties": false }, "ArtistsResponse": { "type": "object", "properties": { "total_count": { "type": "integer" }, "md5": { "type": "string" }, "artist": { "type": "array", "items": { "$ref": "#/components/schemas/ArtistObject" } } }, "required": [ "total_count", "md5", "artist" ], "additionalProperties": false }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "errorCode": { "type": "string" }, "errorAction": { "type": "string" }, "errorType": { "type": "string" }, "errorMessage": { "type": "string" } }, "required": [ "errorCode", "errorAction", "errorType", "errorMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "GenreObject": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "albums": { "type": "integer" }, "artists": { "type": "integer" }, "songs": { "type": "integer" }, "videos": { "type": "integer" }, "playlists": { "type": "integer" }, "live_streams": { "type": "integer" }, "is_hidden": { "type": "boolean" }, "merge": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } } }, "required": [ "id", "name", "albums", "artists", "songs", "videos", "playlists", "live_streams", "is_hidden", "merge" ], "additionalProperties": false }, "GenresResponse": { "type": "object", "properties": { "total_count": { "type": "integer" }, "md5": { "type": "string" }, "genre": { "type": "array", "items": { "$ref": "#/components/schemas/GenreObject" } } }, "required": [ "total_count", "md5", "genre" ], "additionalProperties": false }, "LabelObject": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "artists": { "type": "integer" }, "summary": { "type": "string", "nullable": true }, "external_link": { "type": "string" }, "address": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true }, "user": { "type": "string" } }, "required": [ "id", "name", "artists", "summary", "external_link", "address", "category", "email", "website", "user" ], "additionalProperties": false }, "LabelsResponse": { "type": "object", "properties": { "total_count": { "type": "integer" }, "md5": { "type": "string" }, "label": { "type": "array", "items": { "$ref": "#/components/schemas/LabelObject" } } }, "required": [ "total_count", "md5", "label" ], "additionalProperties": false }, "LiveStreamObject": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true }, "codec": { "type": "string", "nullable": true }, "catalog": { "type": "string" }, "site_url": { "type": "string", "nullable": true } }, "required": [ "id", "name", "url", "codec", "catalog", "site_url" ], "additionalProperties": false }, "LiveStreamsResponse": { "type": "object", "properties": { "total_count": { "type": "integer" }, "md5": { "type": "string" }, "live_stream": { "type": "array", "items": { "$ref": "#/components/schemas/LiveStreamObject" } } }, "required": [ "total_count", "md5", "live_stream" ], "additionalProperties": false }, "PlaylistObject": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "owner": { "type": "string", "nullable": true }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "username": { "type": "string", "nullable": true } }, "required": [ "id", "username" ], "additionalProperties": false }, "items": { "oneOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] } } }, { "type": "integer" } ] }, "type": { "type": "string", "nullable": true }, "art": { "type": "string", "nullable": true }, "has_access": { "type": "boolean" }, "has_collaborate": { "type": "boolean" }, "has_art": { "type": "boolean" }, "flag": { "type": "boolean" }, "rating": { "type": "integer", "nullable": true }, "averagerating": { "type": "number", "nullable": true }, "md5": { "type": "string", "nullable": true }, "last_update": { "type": "integer", "nullable": true }, "time": { "type": "integer" } }, "required": [ "id", "name", "owner", "user", "items", "type", "art", "has_access", "has_collaborate", "has_art", "flag", "rating", "averagerating", "md5", "last_update", "time" ], "additionalProperties": false }, "PlaylistsResponse": { "type": "object", "properties": { "total_count": { "type": "integer" }, "md5": { "type": "string" }, "playlist": { "type": "array", "items": { "$ref": "#/components/schemas/PlaylistObject" } } }, "required": [ "total_count", "md5", "playlist" ], "additionalProperties": false }, "PodcastEpisodeObject": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "podcast": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "description": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true }, "author": { "type": "string", "nullable": true }, "author_full": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true }, "pubdate": { "type": "string", "nullable": true }, "state": { "type": "string" }, "filelength": { "type": "string" }, "filesize": { "type": "string" }, "filename": { "type": "string" }, "mime": { "type": "string", "nullable": true }, "time": { "type": "integer" }, "size": { "type": "integer" }, "bitrate": { "type": "integer" }, "stream_bitrate": { "type": "integer" }, "rate": { "type": "integer" }, "mode": { "type": "string", "nullable": true }, "channels": { "type": "integer", "nullable": true }, "public_url": { "type": "string" }, "url": { "type": "string" }, "catalog": { "type": "string" }, "art": { "type": "string", "nullable": true }, "has_art": { "type": "boolean" }, "flag": { "type": "boolean" }, "rating": { "type": "integer", "nullable": true }, "averagerating": { "type": "number", "nullable": true }, "playcount": { "type": "integer" }, "played": { "type": "string" } }, "required": [ "id", "title", "name", "podcast", "description", "category", "author", "author_full", "website", "pubdate", "state", "filelength", "filesize", "filename", "mime", "time", "size", "bitrate", "stream_bitrate", "rate", "mode", "channels", "public_url", "url", "catalog", "art", "has_art", "flag", "rating", "averagerating", "playcount", "played" ], "additionalProperties": false }, "PodcastEpisodesResponse": { "type": "object", "properties": { "total_count": { "type": "integer" }, "md5": { "type": "string" }, "podcast_episode": { "type": "array", "items": { "$ref": "#/components/schemas/PodcastEpisodeObject" } } }, "required": [ "total_count", "md5", "podcast_episode" ], "additionalProperties": false }, "PodcastObject": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "description": { "type": "string" }, "language": { "type": "string" }, "copyright": { "type": "string" }, "feed_url": { "type": "string" }, "generator": { "type": "string" }, "website": { "type": "string" }, "build_date": { "type": "string" }, "sync_date": { "type": "string" }, "public_url": { "type": "string" }, "art": { "type": "string", "nullable": true }, "has_art": { "type": "boolean" }, "flag": { "type": "boolean" }, "rating": { "type": "integer", "nullable": true }, "averagerating": { "type": "number", "nullable": true }, "podcast_episode": { "type": "array", "items": { "$ref": "#/components/schemas/PodcastEpisodeObject" } } }, "required": [ "id", "name", "description", "language", "copyright", "feed_url", "generator", "website", "build_date", "sync_date", "public_url", "art", "has_art", "flag", "rating", "averagerating", "podcast_episode" ], "additionalProperties": false }, "PodcastsResponse": { "type": "object", "properties": { "total_count": { "type": "integer" }, "md5": { "type": "string" }, "podcast": { "type": "array", "items": { "$ref": "#/components/schemas/PodcastObject" } } }, "required": [ "total_count", "md5", "podcast" ], "additionalProperties": false }, "SongObject": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "artist": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "basename": { "type": "string" } }, "required": [ "id", "name", "prefix", "basename" ], "additionalProperties": false }, "artists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "basename": { "type": "string" } }, "required": [ "id", "name", "prefix", "basename" ], "additionalProperties": false } }, "album": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "basename": { "type": "string" } }, "required": [ "id", "name", "prefix", "basename" ], "additionalProperties": false }, "albumartist": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "basename": { "type": "string" } }, "required": [ "id", "name", "prefix", "basename" ], "additionalProperties": false }, "disk": { "type": "integer" }, "disksubtitle": { "type": "string", "nullable": true }, "track": { "type": "integer" }, "filename": { "type": "string", "nullable": true }, "genre": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "playlisttrack": { "type": "integer" }, "time": { "type": "integer" }, "year": { "type": "integer" }, "format": { "type": "string" }, "stream_format": { "type": "string" }, "bitrate": { "type": "integer" }, "stream_bitrate": { "type": "integer" }, "rate": { "type": "integer" }, "mode": { "type": "string", "nullable": true }, "mime": { "type": "string", "nullable": true }, "stream_mime": { "type": "string", "nullable": true }, "url": { "type": "string" }, "size": { "type": "integer" }, "mbid": { "type": "string", "nullable": true }, "art": { "type": "string", "nullable": true }, "has_art": { "type": "boolean" }, "flag": { "type": "boolean" }, "rating": { "type": "integer", "nullable": true }, "averagerating": { "type": "number", "nullable": true }, "playcount": { "type": "integer" }, "catalog": { "type": "integer" }, "composer": { "type": "string", "nullable": true }, "channels": { "type": "integer", "nullable": true }, "comment": { "type": "string", "nullable": true }, "license": { "type": "string", "nullable": true }, "publisher": { "type": "string", "nullable": true }, "language": { "type": "string", "nullable": true }, "lyrics": { "type": "string", "nullable": true }, "replaygain_album_gain": { "type": "number", "nullable": true }, "replaygain_album_peak": { "type": "number", "nullable": true }, "replaygain_track_gain": { "type": "number", "nullable": true }, "replaygain_track_peak": { "type": "number", "nullable": true }, "r128_album_gain": { "type": "number", "nullable": true }, "r128_track_gain": { "type": "number", "nullable": true } }, "required": [ "id", "title", "name", "artist", "artists", "album", "disk", "disksubtitle", "track", "filename", "genre", "playlisttrack", "time", "year", "format", "stream_format", "bitrate", "stream_bitrate", "rate", "mode", "mime", "stream_mime", "url", "size", "mbid", "art", "has_art", "flag", "rating", "averagerating", "playcount", "catalog", "composer", "channels", "comment", "license", "publisher", "language", "lyrics", "replaygain_album_gain", "replaygain_album_peak", "replaygain_track_gain", "replaygain_track_peak", "r128_album_gain", "r128_track_gain" ], "additionalProperties": true }, "SongsResponse": { "type": "object", "properties": { "total_count": { "type": "integer" }, "md5": { "type": "string" }, "song": { "type": "array", "items": { "$ref": "#/components/schemas/SongObject" } } }, "required": [ "total_count", "md5", "song" ], "additionalProperties": false }, "UserSummaryObject": { "type": "object", "properties": { "id": { "type": "string" }, "username": { "type": "string", "nullable": true } }, "required": [ "id", "username" ], "additionalProperties": false }, "UsersResponse": { "type": "object", "properties": { "user": { "type": "array", "items": { "$ref": "#/components/schemas/UserSummaryObject" } } }, "required": [ "user" ], "additionalProperties": false }, "VideoObject": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string", "nullable": true }, "mime": { "type": "string", "nullable": true }, "resolution": { "type": "string", "nullable": true }, "size": { "type": "integer" }, "genre": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "time": { "type": "integer" }, "url": { "type": "string" }, "art": { "type": "string", "nullable": true }, "has_art": { "type": "boolean" }, "flag": { "type": "boolean" }, "rating": { "type": "integer", "nullable": true }, "averagerating": { "type": "number", "nullable": true }, "playcount": { "type": "integer" } }, "required": [ "id", "title", "mime", "resolution", "size", "genre", "time", "url", "art", "has_art", "flag", "rating", "averagerating", "playcount" ], "additionalProperties": false }, "VideosResponse": { "type": "object", "properties": { "total_count": { "type": "integer" }, "md5": { "type": "string" }, "video": { "type": "array", "items": { "$ref": "#/components/schemas/VideoObject" } } }, "required": [ "total_count", "md5", "video" ], "additionalProperties": false } }, "responses": { "ErrorResponse": { "description": "Ampache API error response payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "BadRequestErrorResponse": { "description": "HTTP 400 Bad Request (errors 4705, 4710).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ForbiddenErrorResponse": { "description": "HTTP 403 Forbidden (errors 4700, 4701, 4703, 4742).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFoundErrorResponse": { "description": "HTTP 404 Not Found (error 4704).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "GoneErrorResponse": { "description": "HTTP 410 Gone (error 4706).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InternalServerErrorResponse": { "description": "HTTP 500 Internal Server Error (error 4702).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuthHeader": [] }, { "ApiKeyAuthQuery": [] } ], "x-rpc-mappings": { "/albums": "action=albums", "/albums/{album_id}": "action=album&filter={album_id}", "/albums/{album_id}/art": "action=get_art&filter={album_id}&type=album", "/albums/{album_id}/fetch-metadata": "action=get_external_metadata&filter={album_id}&type=album", "/albums/{album_id}/flag": "action=flag&filter={album_id}&type=album", "/albums/{album_id}/rate": "action=rate&filter={album_id}&type=album", "/albums/{album_id}/share": "action=share&filter={album_id}&type=album", "/albums/{album_id}/songs": "action=album_songs&filter={album_id}&type=album", "/albums/{album_id}/update-art": "action=update_art&filter={album_id}&type=album", "/albums/{album_id}/update-tags": "action=update_from_tags&filter={album_id}&type=album", "/albums/search": "action=search&type=album", "/albums/stats": "action=stats&type=album", "/artists": "action=artists", "/artists/{artist_id}": "action=artist&filter={artist_id}", "/artists/{artist_id}/albums": "action=artist_albums&filter={artist_id}", "/artists/{artist_id}/art": "action=get_art&filter={artist_id}&type=artist", "/artists/{artist_id}/fetch-info": "action=update_artist_info&filter={artist_id}&type=artist", "/artists/{artist_id}/fetch-metadata": "action=get_external_metadata&filter={artist_id}&type=artist", "/artists/{artist_id}/flag": "action=flag&filter={artist_id}&type=artist", "/artists/{artist_id}/rate": "action=rate&filter={artist_id}&type=artist", "/artists/{artist_id}/share": "action=share&filter={artist_id}&type=artist", "/artists/{artist_id}/similar": "action=get_similar&filter={artist_id}&type=artist", "/artists/{artist_id}/songs": "action=artist_songs&filter={artist_id}&type=artist", "/artists/{artist_id}/update-art": "action=update_art&filter={artist_id}&type=artist", "/artists/{artist_id}/update-tags": "action=update_from_tags&filter={artist_id}&type=artist", "/artists/search": "action=search&type=artist", "/artists/stats": "action=stats&type=artist", "/bookmarks": "action=bookmarks", "PUT /bookmarks": "action=bookmark_create&filter={object_id}&type={object_type}", "/bookmarks/{bookmark_id}": "action=bookmark&filter={bookmark_id}", "DELETE /bookmarks/{bookmark_id}": "action=bookmark_delete&filter={bookmark_id}", "PATCH /bookmarks/{bookmark_id}": "action=bookmark_edit&filter={bookmark_id}", "/browse": "action=browse", "/catalogs": "action=catalogs", "PUT /catalogs": "action=catalog_create", "/catalogs/{catalog_id}": "action=catalog&filter={catalog_id}", "DELETE /catalogs/{catalog_id}": "action=catalog_delete&filter={catalog_id}", "/catalogs/{catalog_id}/file": "action=catalog_file&filter={catalog_id}", "/catalogs/{catalog_id}/folder": "action=catalog_folder&filter={catalog_id}", "/catalogs/{catalog_id}/action": "action=catalog_action&filter={catalog_id}", "/catalogs/{catalog_id}/add": "action=catalog_action&filter={catalog_id}&task=add_to_catalog", "/catalogs/{catalog_id}/clean": "action=catalog_action&filter={catalog_id}&task=clean_catalog", "/catalogs/{catalog_id}/update": "action=catalog_action&filter={catalog_id}&task=update_catalog", "/catalogs/{catalog_id}/verify": "action=catalog_action&filter={catalog_id}&task=verify_catalog", "/catalogs/{catalog_id}/browse": "action=browse&filter={catalog_id}&type=catalog", "/catalogs/{catalog_id}/browse/albums/{album_id}": "action=browse&filter={album_id}&type=album&catalog={catalog_id}", "/catalogs/{catalog_id}/browse/artists/{artist_id}": "action=browse&filter={artist_id}&type=artist&catalog={catalog_id}", "/catalogs/{catalog_id}/browse/podcasts/{podcast_id}": "action=browse&filter={podcast_id}&type=podcast&catalog={catalog_id}", "/democratic/{object_id}": "action=democratic&filter={object_id}", "/democratic/{object_id}/localplay": "action=localplay&filter={object_id}&type=democratic", "/genres": "action=genres", "/genres/{genre_id}": "action=genre&filter={genre_id}", "/genres/{genre_id}/albums": "action=genre_albums&filter={genre_id}", "/genres/{genre_id}/artists": "action=genre_artists&filter={genre_id}", "/genres/{genre_id}/songs": "action=genre_songs&filter={genre_id}", "/genres/search": "action=search&type=genre", "/goodbye": "action=goodbye", "/handshake": "action=handshake", "/index": "action=index", "/labels": "action=labels", "/labels/{label_id}": "action=label&filter={label_id}", "/labels/{label_id}/artists": "action=label_artists&filter={label_id}", "/labels/{label_id}/fetch-metadata": "action=get_external_metadata&filter={label_id}&type=label", "/labels/search": "action=search&type=label", "/licenses": "action=licenses", "/licenses/{license_id}": "action=license&filter={license_id}", "/licenses/{license_id}/songs": "action=license_songs&filter={license_id}", "/list": "action=list", "/live-streams": "action=live_streams", "PUT /live-streams": "action=live_stream_create", "/live-streams/{live_stream_id}": "action=live_stream&filter={live_stream_id}", "PATCH /live-streams/{live_stream_id}": "action=live_stream_edit&filter={live_stream_id}", "DELETE /live-streams/{live_stream_id}": "action=live_stream_delete&filter={live_stream_id}", "/live-streams/{live_stream_id}/localplay": "action=localplay&command=add&filter={live_stream_id}&type=live_stream", "/localplay/add": "action=localplay&command=add&filter={object_id}&type={object_type}", "/localplay/delete-all": "action=localplay&command=delete_all", "/localplay/next": "action=localplay&command=next", "/localplay/pause": "action=localplay&command=pause", "/localplay/play": "action=localplay&command=play", "/localplay/prev": "action=localplay&command=prev", "/localplay/skip": "action=localplay&command=skip", "/localplay/status": "action=localplay&command=status", "/localplay/stop": "action=localplay&command=stop", "/localplay/volume-down": "action=localplay&command=volume_down", "/localplay/volume-mute": "action=localplay&command=volume_mute", "/localplay/volume-up": "action=localplay&command=volume_up", "/me": "action=user", "/me/friends-timeline": "action=friends_timeline", "/me/last-shouts": "action=last_shouts", "/me/lost-password": "action=lost_password", "/me/now-playing": "action=now_playing", "/me/playlists": "action=user_playlists", "/me/smartlists": "action=user_smartlists", "/ping": "action=ping", "/playlists": "action=playlists", "PUT /playlists": "action=playlist_create", "/playlists/{playlist_id}": "action=playlist&filter={playlist_id}", "PATCH /playlists/{playlist_id}": "action=playlist_edit&filter={playlist_id}", "DELETE /playlists/{playlist_id}": "action=playlist_delete&filter={playlist_id}", "/playlists/{playlist_id}/add": "action=playlist_add&filter={playlist_id}", "/playlists/{playlist_id}/art": "action=get_art&filter={playlist_id}&type=playlist", "/playlists/{playlist_id}/download": "action=download&filter={playlist_id}&type=playlist", "/playlists/{playlist_id}/flag": "action=flag&filter={playlist_id}", "/playlists/{playlist_id}/hash": "action=playlist_hash&filter={playlist_id}", "/playlists/{playlist_id}/rate": "action=rate&filter={playlist_id}", "/playlists/{playlist_id}/remove-song": "action=playlist_remove_song&filter={playlist_id}&song={song_id}", "/playlists/{playlist_id}/share": "action=share&filter={playlist_id}", "/playlists/{playlist_id}/songs": "action=playlist_songs&filter={playlist_id}", "/playlists/{playlist_id}/stream": "action=stream&filter={playlist_id}&type=playlist", "/playlists/search": "action=search&type=playlist", "/playlists/stats": "action=stats&type=playlist", "/podcast-episodes": "action=podcast_episodes", "/podcast-episodes/{episode_id}": "action=podcast_episode&filter={episode_id}", "DELETE /podcast-episodes/{episode_id}": "action=podcast_episode_delete&filter={episode_id}", "/podcast-episodes/{episode_id}/bookmark": "action=bookmark_create&filter={episode_id}&type=podcast_episode", "GET /podcast-episodes/{episode_id}/bookmark": "action=bookmark&filter={episode_id}&type=podcast_episode", "PATCH /podcast-episodes/{episode_id}/bookmark": "action=bookmark_edit&filter={episode_id}&type=podcast_episode", "DELETE /podcast-episodes/{episode_id}/bookmark": "action=bookmark_delete&filter={episode_id}&type=podcast_episode", "/podcast-episodes/{episode_id}/download": "action=download&filter={episode_id}&type=podcast_episode", "/podcast-episodes/{episode_id}/flag": "action=flag&filter={episode_id}&type=podcast_episode", "/podcast-episodes/{episode_id}/localplay": "action=localplay&command=add&filter={episode_id}&type=podcast_episode", "/podcast-episodes/{episode_id}/playback": "action=player&filter={episode_id}&type=podcast_episode", "/podcast-episodes/{episode_id}/rate": "action=rate&filter={episode_id}&type=podcast_episode", "/podcast-episodes/{episode_id}/share": "action=share&filter={episode_id}&type=podcast_episode", "/podcast-episodes/{episode_id}/stream": "action=stream&filter={episode_id}&type=podcast_episode", "/podcast-episodes/deleted": "action=deleted_podcast_episodes", "/podcast-episodes/search": "action=search&type=podcast_episode", "/podcast-episodes/stats": "action=stats&type=podcast_episode", "/podcasts": "action=podcasts", "PUT /podcasts": "action=podcast_create", "/podcasts/{podcast_id}": "action=podcast&filter={podcast_id}", "PATCH /podcasts/{podcast_id}": "action=podcast_edit&filter={podcast_id}", "DELETE /podcasts/{podcast_id}": "action=podcast_delete&filter={podcast_id}", "/podcasts/{podcast_id}/art": "action=get_art&filter={podcast_id}&type=podcast", "/podcasts/{podcast_id}/flag": "action=flag&filter={podcast_id}", "/podcasts/{podcast_id}/podcast-episodes": "action=podcast_episodes&filter={podcast_id}", "/podcasts/{podcast_id}/rate": "action=rate&filter={podcast_id}", "/podcasts/{podcast_id}/share": "action=share&filter={podcast_id}", "/podcasts/search": "action=search&type=podcast", "/podcasts/stats": "action=stats&type=podcast", "/podcasts/{podcast_id}/sync": "action=update_podcast&filter={podcast_id}", "/preferences": "action=user_preferences", "PUT /preferences": "action=preference_create", "/preferences/{preference_name}": "action=user_preference&filter={preference_name}", "PATCH /preferences/{preference_name}": "action=preference_edit&filter={preference_name}", "DELETE /preferences/{preference_name}": "action=preference_delete&filter={preference_name}", "/register": "action=register", "/scrobble": "action=scrobble", "/search/{search_type}/groups": "action=search_group&filter={search_type}", "/search/{search_type}/rules": "action=search_rules&filter={search_type}", "/shares": "action=shares", "PUT /shares": "action=share_create", "/shares/{share_id}": "action=share&filter={share_id}", "DELETE /shares/{share_id}": "action=share_delete&filter={share_id}", "PATCH /shares/{share_id}": "action=share_edit&filter={share_id}", "/smartlists": "action=smartlists", "/smartlists/{smartlist_id}": "action=smartlist&filter={smartlist_id}", "DELETE /smartlists/{smartlist_id}": "action=smartlist_delete&filter={smartlist_id}", "/smartlists/{smartlist_id}/art": "action=get_art&filter={smartlist_id}&type=smartlist", "/smartlists/{smartlist_id}/download": "action=download&filter={smartlist_id}&type=smartlist", "/smartlists/{smartlist_id}/flag": "action=flag&filter={smartlist_id}&type=smartlist", "/smartlists/{smartlist_id}/rate": "action=rate&filter={smartlist_id}&type=smartlist", "/smartlists/{smartlist_id}/share": "action=share&filter={smartlist_id}&type=smartlist", "/smartlists/{smartlist_id}/songs": "action=smartlist_songs&filter={smartlist_id}", "/smartlists/{smartlist_id}/stream": "action=stream&filter={smartlist_id}&type=smartlist", "/songs": "action=songs", "/songs/{song_id}": "action=song&filter={song_id}", "DELETE /songs/{song_id}": "action=song_delete&filter={song_id}", "/songs/{song_id}/art": "action=get_art&filter={song_id}&type=song", "/songs/{song_id}/bookmark": "action=bookmark_create&filter={song_id}&type=song", "GET /songs/{song_id}/bookmark": "action=bookmark&filter={song_id}&type=song", "PATCH /songs/{song_id}/bookmark": "action=bookmark_edit&filter={song_id}&type=song", "DELETE /songs/{song_id}/bookmark": "action=bookmark_delete&filter={song_id}&type=song", "/songs/{song_id}/download": "action=download&filter={song_id}", "/songs/{song_id}/fetch-metadata": "action=get_external_metadata&filter={song_id}&type=song", "/songs/{song_id}/flag": "action=flag&filter={song_id}", "/songs/{song_id}/localplay": "action=localplay&command=add&filter={song_id}&type=song", "/songs/{song_id}/lyrics": "action=get_lyrics&filter={song_id}", "/songs/{song_id}/playback": "action=player&filter={song_id}&type=song", "/songs/{song_id}/rate": "action=rate&filter={song_id}", "/songs/{song_id}/record-play": "action=record_play&filter={song_id}", "/songs/{song_id}/share": "action=share&filter={song_id}", "/songs/{song_id}/similar": "action=get_similar&filter={song_id}&type=song", "/songs/{song_id}/stream": "action=stream&filter={song_id}&type=song", "/songs/{song_id}/tags": "action=song_tags&filter={song_id}", "/songs/{song_id}/update-tags": "action=update_from_tags&filter={song_id}&type=song", "/songs/deleted": "action=deleted_songs", "/songs/lookup/url-to-song": "action=url_to_song", "/songs/playlist-generate": "action=playlist_generate", "/songs/search": "action=search&type=song", "/songs/stats": "action=stats&type=song", "/system-preferences": "action=system_preferences", "/system-preferences/{preference_name}": "action=system_preference&filter={preference_name}", "/update": "action=system_update", "/users": "action=users", "PUT /users": "action=user_create", "/users/{user_id}": "action=user&filter={user_id}", "DELETE /users/{user_id}": "action=user_delete&filter={user_id}", "/users/{user_id}/follow": "action=toggle_follow&filter={user_id}", "/users/{user_id}/followers": "action=followers&filter={user_id}", "/users/{user_id}/following": "action=following&filter={user_id}", "/users/{user_id}/timeline": "action=timeline&filter={user_id}", "/users/search": "action=search&type=user", "PATCH /users/{user_id}": "action=user_edit&filter={user_id}", "/videos": "action=videos", "/videos/{video_id}": "action=video&filter={video_id}", "/videos/{video_id}/bookmark": "action=bookmark_create&filter={video_id}&type=video", "GET /videos/{video_id}/bookmark": "action=bookmark&filter={video_id}&type=video", "PATCH /videos/{video_id}/bookmark": "action=bookmark_edit&filter={video_id}&type=video", "DELETE /videos/{video_id}/bookmark": "action=bookmark_delete&filter={video_id}&type=video", "/videos/{video_id}/flag": "action=flag&filter={video_id}&type=video", "/videos/{video_id}/localplay": "action=localplay&command=add&filter={video_id}&type=video", "/videos/{video_id}/playback": "action=player&filter={video_id}&type=video", "/videos/{video_id}/rate": "action=rate&filter={video_id}&type=video", "/videos/{video_id}/share": "action=share&filter={video_id}&type=video", "/videos/deleted": "action=deleted_videos", "/videos/search": "action=search&type=video", "/videos/stats": "action=stats&type=video" }, "paths": { "/albums": { "get": { "parameters": [ { "in": "query", "name": "filter", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "include", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "exact", "required": false, "schema": { "type": "boolean" } }, { "in": "query", "name": "add", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "update", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlbumsResponse" } } }, "description": "Albums list" } }, "summary": "List albums", "tags": [ "Albums" ] } }, "/albums/{album_id}": { "get": { "parameters": [ { "in": "path", "name": "album_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "include", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlbumObject" } } }, "description": "Album details" } }, "summary": "Get album by ID", "tags": [ "Albums" ] } }, "/albums/{album_id}/art": { "get": { "parameters": [ { "in": "path", "name": "album_id", "required": true, "schema": { "type": "string" } }, { "description": "widthxheight, e.g. 640x480", "in": "query", "name": "size", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Binary image response" } }, "summary": "Get art image (binary)", "tags": [ "Artwork" ] } }, "/albums/{album_id}/fetch-metadata": { "get": { "parameters": [ { "in": "path", "name": "album_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "External metadata array" } }, "summary": "Get external metadata for an album", "tags": [ "Albums", "Utilities" ] } }, "/albums/{album_id}/flag": { "post": { "parameters": [ { "in": "path", "name": "album_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "flag", "required": true, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Updated" } }, "summary": "Flag or unflag an item as favourite", "tags": [ "Ratings and Flags" ] } }, "/albums/{album_id}/rate": { "post": { "parameters": [ { "in": "path", "name": "album_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "rating", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Success" } }, "summary": "Rate a library item", "tags": [ "Ratings and Flags" ] } }, "/albums/{album_id}/share": { "post": { "parameters": [ { "description": "UID of object you are sharing", "in": "path", "name": "album_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "description", "required": false, "schema": { "type": "string" } }, { "description": "days to keep active", "in": "query", "name": "expires", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Share created" } }, "summary": "Create a public share URL", "tags": [ "Shares" ] } }, "/albums/{album_id}/songs": { "get": { "parameters": [ { "in": "path", "name": "album_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "top50", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SongsResponse" } } }, "description": "Song list" } }, "summary": "Get songs for an album", "tags": [ "Albums", "Songs" ] } }, "/albums/{album_id}/update-art": { "post": { "parameters": [ { "in": "path", "name": "album_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "overwrite", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Updated" } }, "summary": "Update art for an object (Catalog Manager)", "tags": [ "Utilities" ] } }, "/albums/{album_id}/update-tags": { "post": { "parameters": [ { "in": "path", "name": "album_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Updated" } }, "summary": "Update object metadata from tags", "tags": [ "Utilities" ] } }, "/albums/search": { "get": { "description": "Provide operator plus one or more rule triplets. At minimum, rule_1, rule_1_operator, rule_1_input are required. Additional rules may be supplied as rule_2, rule_2_operator, rule_2_input, etc.", "operationId": "album-search", "parameters": [ { "description": "and, or (whether to match one rule or all)", "in": "query", "name": "operator", "required": true, "schema": { "enum": [ "and", "or" ], "type": "string" } }, { "description": "0, 1 (random order of results; default to 0)", "in": "query", "name": "random", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Return results starting from this index position", "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "type": "integer" } }, { "description": "Maximum number of results to return", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 500, "minimum": 1, "type": "integer" } }, { "description": "Rule field/key for rule 1", "in": "query", "name": "rule_1", "required": true, "schema": { "type": "string" } }, { "description": "Operator for rule 1", "in": "query", "name": "rule_1_operator", "required": true, "schema": { "type": "string" } }, { "description": "Input value for rule 1", "in": "query", "name": "rule_1_input", "required": true, "schema": { "type": "string" } }, { "description": "Rule field/key for rule 2", "in": "query", "name": "rule_2", "required": false, "schema": { "type": "string" } }, { "description": "Operator for rule 2", "in": "query", "name": "rule_2_operator", "required": false, "schema": { "type": "string" } }, { "description": "Input value for rule 2", "in": "query", "name": "rule_2_input", "required": false, "schema": { "type": "string" } }, { "description": "Rule field/key for rule 3", "in": "query", "name": "rule_3", "required": false, "schema": { "type": "string" } }, { "description": "Operator for rule 3", "in": "query", "name": "rule_3_operator", "required": false, "schema": { "type": "string" } }, { "description": "Input value for rule 3", "in": "query", "name": "rule_3_input", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Search results" } }, "summary": "Search for media entities using rule triplets", "tags": [ "Albums", "Search" ] } }, "/albums/stats": { "get": { "parameters": [ { "description": "newest, highest, frequent, recent, forgotten, flagged, random", "in": "query", "name": "filter", "required": true, "schema": { "default": "random", "enum": [ "newest", "highest", "frequent", "recent", "forgotten", "flagged", "random" ], "type": "string" } }, { "in": "query", "name": "user_id", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "username", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Stats result" } }, "summary": "Get stats (song/album/artist etc) by type and filter", "tags": [ "Browsing, Indexes and Lists" ] } }, "/artists": { "get": { "parameters": [ { "in": "query", "name": "filter", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "exact", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "add", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "update", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "albums,songs", "in": "query", "name": "include", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "album_artist", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtistsResponse" } } }, "description": "Artist list" } }, "summary": "List artists", "tags": [ "Artists" ] } }, "/artists/{artist_id}": { "get": { "parameters": [ { "in": "path", "name": "artist_id", "required": true, "schema": { "type": "string" } }, { "description": "albums,songs", "in": "query", "name": "include", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtistObject" } } }, "description": "Artist object" } }, "summary": "Get artist by ID", "tags": [ "Artists" ] } }, "/artists/{artist_id}/albums": { "get": { "parameters": [ { "in": "path", "name": "artist_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "album_artist", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlbumsResponse" } } }, "description": "Album list" } }, "summary": "Get albums for an artist", "tags": [ "Albums", "Artists" ] } }, "/artists/{artist_id}/art": { "get": { "parameters": [ { "in": "path", "name": "artist_id", "required": true, "schema": { "type": "string" } }, { "description": "widthxheight, e.g. 640x480", "in": "query", "name": "size", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Binary image response" } }, "summary": "Get art image (binary)", "tags": [ "Artwork" ] } }, "/artists/{artist_id}/fetch-info": { "post": { "parameters": [ { "in": "path", "name": "artist_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Updated" } }, "summary": "Update artist info and fetch similar artists", "tags": [ "Utilities" ] } }, "/artists/{artist_id}/fetch-metadata": { "get": { "parameters": [ { "in": "path", "name": "artist_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "External metadata array" } }, "summary": "Get external metadata for an artist", "tags": [ "Artists", "Utilities" ] } }, "/artists/{artist_id}/flag": { "post": { "parameters": [ { "in": "path", "name": "artist_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "flag", "required": true, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Updated" } }, "summary": "Flag or unflag an item as favourite", "tags": [ "Ratings and Flags" ] } }, "/artists/{artist_id}/rate": { "post": { "parameters": [ { "in": "path", "name": "artist_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "rating", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Success" } }, "summary": "Rate a library item", "tags": [ "Ratings and Flags" ] } }, "/artists/{artist_id}/share": { "post": { "parameters": [ { "description": "UID of object you are sharing", "in": "path", "name": "artist_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "description", "required": false, "schema": { "type": "string" } }, { "description": "days to keep active", "in": "query", "name": "expires", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Share created" } }, "summary": "Create a public share URL", "tags": [ "Shares" ] } }, "/artists/{artist_id}/similar": { "get": { "parameters": [ { "in": "path", "name": "artist_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Similar list" } }, "summary": "Get similar artists", "tags": [ "Artists" ] } }, "/artists/{artist_id}/songs": { "get": { "parameters": [ { "in": "path", "name": "artist_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "top50", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SongsResponse" } } }, "description": "Song list" } }, "summary": "Get songs for an artist", "tags": [ "Artists", "Songs" ] } }, "/artists/{artist_id}/update-art": { "post": { "parameters": [ { "in": "path", "name": "artist_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "overwrite", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Updated" } }, "summary": "Update art for an object (Catalog Manager)", "tags": [ "Utilities" ] } }, "/artists/{artist_id}/update-tags": { "post": { "parameters": [ { "in": "path", "name": "artist_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Updated" } }, "summary": "Update object metadata from tags", "tags": [ "Utilities" ] } }, "/artists/search": { "get": { "description": "Provide operator plus one or more rule triplets. At minimum, rule_1, rule_1_operator, rule_1_input are required. Additional rules may be supplied as rule_2, rule_2_operator, rule_2_input, etc.", "operationId": "artist-search", "parameters": [ { "description": "and, or (whether to match one rule or all)", "in": "query", "name": "operator", "required": true, "schema": { "enum": [ "and", "or" ], "type": "string" } }, { "description": "Specify the subtype of artist to search for", "in": "query", "name": "subtype", "required": false, "schema": { "enum": [ "album_artists", "song_artists" ], "type": "string" } }, { "description": "0, 1 (random order of results; default to 0)", "in": "query", "name": "random", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Return results starting from this index position", "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "type": "integer" } }, { "description": "Maximum number of results to return", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 500, "minimum": 1, "type": "integer" } }, { "description": "Rule field/key for rule 1", "in": "query", "name": "rule_1", "required": true, "schema": { "type": "string" } }, { "description": "Operator for rule 1", "in": "query", "name": "rule_1_operator", "required": true, "schema": { "type": "string" } }, { "description": "Input value for rule 1", "in": "query", "name": "rule_1_input", "required": true, "schema": { "type": "string" } }, { "description": "Rule field/key for rule 2", "in": "query", "name": "rule_2", "required": false, "schema": { "type": "string" } }, { "description": "Operator for rule 2", "in": "query", "name": "rule_2_operator", "required": false, "schema": { "type": "string" } }, { "description": "Input value for rule 2", "in": "query", "name": "rule_2_input", "required": false, "schema": { "type": "string" } }, { "description": "Rule field/key for rule 3", "in": "query", "name": "rule_3", "required": false, "schema": { "type": "string" } }, { "description": "Operator for rule 3", "in": "query", "name": "rule_3_operator", "required": false, "schema": { "type": "string" } }, { "description": "Input value for rule 3", "in": "query", "name": "rule_3_input", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Search results" } }, "summary": "Search for media entities using rule triplets", "tags": [ "Artists", "Search" ] } }, "/artists/stats": { "get": { "parameters": [ { "description": "newest, highest, frequent, recent, forgotten, flagged, random", "in": "query", "name": "filter", "required": true, "schema": { "default": "random", "enum": [ "newest", "highest", "frequent", "recent", "forgotten", "flagged", "random" ], "type": "string" } }, { "in": "query", "name": "user_id", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "username", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Stats result" } }, "summary": "Get stats (song/album/artist etc) by type and filter", "tags": [ "Browsing, Indexes and Lists" ] } }, "/bookmarks": { "get": { "parameters": [ { "in": "query", "name": "client", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "include", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Bookmark list" } }, "summary": "List bookmarks", "tags": [ "Bookmarks" ] }, "put": { "parameters": [ { "in": "query", "name": "filter", "description": "Object id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "type", "required": true, "schema": { "enum": [ "song", "video", "podcast_episode" ], "type": "string" } }, { "in": "query", "name": "position", "description": "Current track time in seconds", "required": true, "schema": { "type": "integer" } }, { "in": "query", "name": "client", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "date", "description": "UNIXTIME()", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "include", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Bookmark created" } }, "summary": "Create a bookmark", "tags": [ "Bookmarks" ] } }, "/bookmarks/{bookmark_id}": { "delete": { "parameters": [ { "description": "bookmark_id", "in": "path", "name": "bookmark_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "client", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Success" } }, "summary": "Delete a bookmark", "tags": [ "Bookmarks" ] }, "get": { "parameters": [ { "in": "path", "name": "bookmark_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "include", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Bookmark object" } }, "summary": "Get bookmark by ID", "tags": [ "Bookmarks" ] }, "patch": { "parameters": [ { "description": "bookmark_id", "in": "path", "name": "bookmark_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "position", "required": true, "schema": { "type": "integer" } }, { "in": "query", "name": "client", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "date", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "include", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Bookmark array" } }, "summary": "Edit a bookmark", "tags": [ "Bookmarks" ] } }, "/browse": { "get": { "parameters": [ { "in": "query", "name": "filter", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "type", "required": false, "schema": { "enum": [ "root", "catalog", "artist", "album", "podcast" ], "type": "string" } }, { "in": "query", "name": "catalog", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "add", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "update", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Browse array" } }, "summary": "Browse folder-style children", "tags": [ "Browsing, Indexes and Lists" ] } }, "/catalogs": { "get": { "parameters": [ { "description": "music,clip,tvshow,movie,personal_video,podcast", "in": "query", "name": "filter", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Catalog list" } }, "summary": "List catalogs", "tags": [ "Catalogs" ] }, "put": { "parameters": [ { "in": "query", "name": "name", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "path", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "type", "required": false, "schema": { "enum": [ "local", "beets", "remote", "subsonic", "seafile", "beetsremote" ], "type": "string" } }, { "in": "query", "name": "media_type", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "file_pattern", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "folder_pattern", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "username", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "password", "required": false, "schema": { "type": "string" }, "deprecated": true, "description": "Deprecated: for privacy, send this in a form or JSON request body instead of the query string (query values land in server/proxy logs and browser history). Query-string support will be removed in API9." } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Catalog object" } }, "summary": "Create a catalog", "tags": [ "Catalogs" ] } }, "/catalogs/{catalog_id}": { "delete": { "parameters": [ { "in": "path", "name": "catalog_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Success" } }, "summary": "Delete a catalog", "tags": [ "Catalogs" ] }, "get": { "parameters": [ { "in": "path", "name": "catalog_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Catalog object" } }, "summary": "Get catalog by ID", "tags": [ "Catalogs" ] } }, "/catalogs/{catalog_id}/action": { "post": { "parameters": [ { "in": "path", "name": "catalog_id", "required": true, "schema": { "type": "string" } }, { "description": "Catalog task to run", "in": "query", "name": "task", "required": true, "schema": { "enum": [ "add_to_catalog", "clean_catalog", "verify_catalog", "gather_art", "garbage_collect" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Success" } }, "summary": "Kick off a catalog task (add/clean/verify/gather art) for the selected catalog", "tags": [ "Catalogs" ] } }, "/catalogs/{catalog_id}/browse": { "get": { "parameters": [ { "in": "path", "name": "catalog_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "add", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "update", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Browse results" } }, "summary": "Browse children of a catalog (root of the catalog)", "tags": [ "Catalogs" ] } }, "/catalogs/{catalog_id}/browse/albums/{album_id}": { "get": { "parameters": [ { "in": "path", "name": "catalog_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "album_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "add", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "update", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Browse results" } }, "summary": "Browse songs of an album within a catalog", "tags": [ "Catalogs" ] } }, "/catalogs/{catalog_id}/browse/artists/{artist_id}": { "get": { "parameters": [ { "in": "path", "name": "catalog_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "artist_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "add", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "update", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Browse results" } }, "summary": "Browse albums of an artist within a catalog", "tags": [ "Catalogs" ] } }, "/catalogs/{catalog_id}/browse/podcasts/{podcast_id}": { "get": { "parameters": [ { "in": "path", "name": "catalog_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "podcast_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "add", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "update", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Browse results" } }, "summary": "Browse episodes of a podcast within a catalog", "tags": [ "Catalogs" ] } }, "/catalogs/{catalog_id}/file": { "post": { "parameters": [ { "in": "path", "name": "catalog_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "file", "required": true, "schema": { "type": "string" } }, { "description": "add,clean,verify,remove (comma-separated allowed)", "in": "query", "name": "task", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Success" } }, "summary": "Perform actions on a catalog file", "tags": [ "Catalogs" ] } }, "/catalogs/{catalog_id}/folder": { "get": { "parameters": [ { "in": "path", "name": "catalog_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "folder", "required": true, "schema": { "type": "string" } }, { "description": "add,clean,verify,remove (comma-separated allowed)", "in": "query", "name": "task", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Success" } }, "summary": "Perform actions on a catalog folder", "tags": [ "Catalogs" ], "description": "Resolves to the same `catalog_folder` action as POST; the REST layer only suffixes DELETE, PATCH and PUT." }, "post": { "parameters": [ { "in": "path", "name": "catalog_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "folder", "required": true, "schema": { "type": "string" } }, { "description": "add,clean,verify,remove (comma-separated allowed)", "in": "query", "name": "task", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Success" } }, "summary": "Perform actions on a catalog folder", "tags": [ "Catalogs" ] } }, "/democratic/{object_id}": { "post": { "parameters": [ { "description": "Song object id", "in": "path", "name": "object_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "method", "required": true, "schema": { "enum": [ "vote", "devote", "playlist", "play" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Democratic response" } }, "summary": "Control democratic play", "tags": [ "Playback Control" ] } }, "/democratic/{object_id}/localplay": { "post": { "parameters": [ { "description": "Media object id", "in": "path", "name": "object_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "command", "required": true, "schema": { "enum": [ "add" ], "type": "string" } }, { "in": "query", "name": "type", "required": false, "schema": { "enum": [ "song", "video", "podcast_episode", "channel", "broadcast", "democratic", "live_stream" ], "type": "string" } }, { "in": "query", "name": "clear", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Localplay response" } }, "summary": "Add media to the localplay server", "tags": [ "Playback Control" ] } }, "/genres": { "get": { "parameters": [ { "in": "query", "name": "filter", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "exact", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenresResponse" } } }, "description": "Genre list" } }, "summary": "List genres", "tags": [ "Genres" ] } }, "/genres/{genre_id}": { "get": { "parameters": [ { "in": "path", "name": "genre_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenreObject" } } }, "description": "Genre object" } }, "summary": "Get genre by ID", "tags": [ "Genres" ] } }, "/genres/{genre_id}/albums": { "get": { "parameters": [ { "in": "path", "name": "genre_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlbumsResponse" } } }, "description": "Album list" } }, "summary": "Get albums for a genre", "tags": [ "Genres", "Albums" ] } }, "/genres/{genre_id}/artists": { "get": { "parameters": [ { "in": "path", "name": "genre_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtistsResponse" } } }, "description": "Artist list" } }, "summary": "Get artists for a genre", "tags": [ "Genres", "Artists" ] } }, "/genres/{genre_id}/songs": { "get": { "parameters": [ { "in": "path", "name": "genre_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SongsResponse" } } }, "description": "Song list" } }, "summary": "Get songs for a genre", "tags": [ "Genres", "Songs" ] } }, "/genres/search": { "get": { "description": "Provide operator plus one or more rule triplets. At minimum, rule_1, rule_1_operator, rule_1_input are required. Additional rules may be supplied as rule_2, rule_2_operator, rule_2_input, etc.", "operationId": "genre-search", "parameters": [ { "description": "and, or (whether to match one rule or all)", "in": "query", "name": "operator", "required": true, "schema": { "enum": [ "and", "or" ], "type": "string" } }, { "description": "0, 1 (random order of results; default to 0)", "in": "query", "name": "random", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Return results starting from this index position", "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "type": "integer" } }, { "description": "Maximum number of results to return", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 500, "minimum": 1, "type": "integer" } }, { "description": "Rule field/key for rule 1", "in": "query", "name": "rule_1", "required": true, "schema": { "type": "string" } }, { "description": "Operator for rule 1", "in": "query", "name": "rule_1_operator", "required": true, "schema": { "type": "string" } }, { "description": "Input value for rule 1", "in": "query", "name": "rule_1_input", "required": true, "schema": { "type": "string" } }, { "description": "Rule field/key for rule 2", "in": "query", "name": "rule_2", "required": false, "schema": { "type": "string" } }, { "description": "Operator for rule 2", "in": "query", "name": "rule_2_operator", "required": false, "schema": { "type": "string" } }, { "description": "Input value for rule 2", "in": "query", "name": "rule_2_input", "required": false, "schema": { "type": "string" } }, { "description": "Rule field/key for rule 3", "in": "query", "name": "rule_3", "required": false, "schema": { "type": "string" } }, { "description": "Operator for rule 3", "in": "query", "name": "rule_3_operator", "required": false, "schema": { "type": "string" } }, { "description": "Input value for rule 3", "in": "query", "name": "rule_3_input", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Search results" } }, "summary": "Search for media entities using rule triplets", "tags": [ "Genres", "Search" ] } }, "/goodbye": { "post": { "description": "Destroy auth session.", "parameters": [ { "in": "query", "name": "auth", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Success" } }, "security": [ { "ApiKeyAuthHeader": [] }, { "ApiKeyAuthQuery": [] } ], "summary": "Destroy a session", "tags": [ "Authentication" ] } }, "/handshake": { "post": { "description": "When you do not have an API key you can request a session token using handshake which can then be used as your authentication token.", "parameters": [ { "description": "Passphrase (timestamp + password hash) or API key. Required unless using BearerAuth. Deprecated: for privacy, send this in a request body or the `Authorization: Bearer` header instead of the query string. Query-string support will be removed in API9.", "in": "query", "name": "auth", "required": false, "schema": { "type": "string" }, "deprecated": true }, { "description": "Username (required for login/password authentication).", "in": "query", "name": "user", "required": false, "schema": { "type": "string" } }, { "description": "UNIX time used in seed of password hash (required for login/password authentication).", "in": "query", "name": "timestamp", "required": false, "schema": { "type": "integer" } }, { "description": "API version the client understands.", "in": "query", "name": "version", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } }, "application/xml": { "schema": { "type": "string" } } }, "description": "Session info or error" } }, "security": [ {}, { "ApiKeyAuthHeader": [] }, { "ApiKeyAuthQuery": [] } ], "summary": "Authenticate and start a session (deprecated)", "tags": [ "Authentication" ] } }, "/index": { "get": { "parameters": [ { "in": "query", "name": "type", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "filter", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "hide_search", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "exact", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "add", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "update", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "include", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Index response" } }, "summary": "Index IDs for an object type", "tags": [ "Browsing, Indexes and Lists" ] } }, "/labels": { "get": { "parameters": [ { "in": "query", "name": "filter", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "exact", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "add", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "update", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelsResponse" } } }, "description": "Label list" } }, "summary": "List labels", "tags": [ "Labels" ] } }, "/labels/{label_id}": { "get": { "parameters": [ { "in": "path", "name": "label_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelObject" } } }, "description": "Label object" } }, "summary": "Get label by ID", "tags": [ "Labels" ] } }, "/labels/{label_id}/artists": { "get": { "parameters": [ { "in": "path", "name": "label_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtistsResponse" } } }, "description": "Artist list" } }, "summary": "Get artists for a label", "tags": [ "Labels", "Artists" ] } }, "/labels/{label_id}/fetch-metadata": { "get": { "parameters": [ { "in": "path", "name": "label_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "External metadata array" } }, "summary": "Get external metadata for a label", "tags": [ "Labels", "Utilities" ] } }, "/labels/search": { "get": { "description": "Provide operator plus one or more rule triplets. At minimum, rule_1, rule_1_operator, rule_1_input are required. Additional rules may be supplied as rule_2, rule_2_operator, rule_2_input, etc.", "operationId": "label-search", "parameters": [ { "description": "and, or (whether to match one rule or all)", "in": "query", "name": "operator", "required": true, "schema": { "enum": [ "and", "or" ], "type": "string" } }, { "description": "0, 1 (random order of results; default to 0)", "in": "query", "name": "random", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Return results starting from this index position", "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "type": "integer" } }, { "description": "Maximum number of results to return", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 500, "minimum": 1, "type": "integer" } }, { "description": "Rule field/key for rule 1", "in": "query", "name": "rule_1", "required": true, "schema": { "type": "string" } }, { "description": "Operator for rule 1", "in": "query", "name": "rule_1_operator", "required": true, "schema": { "type": "string" } }, { "description": "Input value for rule 1", "in": "query", "name": "rule_1_input", "required": true, "schema": { "type": "string" } }, { "description": "Rule field/key for rule 2", "in": "query", "name": "rule_2", "required": false, "schema": { "type": "string" } }, { "description": "Operator for rule 2", "in": "query", "name": "rule_2_operator", "required": false, "schema": { "type": "string" } }, { "description": "Input value for rule 2", "in": "query", "name": "rule_2_input", "required": false, "schema": { "type": "string" } }, { "description": "Rule field/key for rule 3", "in": "query", "name": "rule_3", "required": false, "schema": { "type": "string" } }, { "description": "Operator for rule 3", "in": "query", "name": "rule_3_operator", "required": false, "schema": { "type": "string" } }, { "description": "Input value for rule 3", "in": "query", "name": "rule_3_input", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Search results" } }, "summary": "Search for media entities using rule triplets", "tags": [ "Labels", "Search" ] } }, "/licenses": { "get": { "parameters": [ { "in": "query", "name": "filter", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "exact", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "add", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "update", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "License list" } }, "summary": "List licenses", "tags": [ "Licenses" ] } }, "/licenses/{license_id}": { "get": { "parameters": [ { "in": "path", "name": "license_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "License object" } }, "summary": "Get license by ID", "tags": [ "Licenses" ] } }, "/licenses/{license_id}/songs": { "get": { "parameters": [ { "in": "path", "name": "license_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SongsResponse" } } }, "description": "Song list" } }, "summary": "Get songs for a license", "tags": [ "Licenses", "Songs" ] } }, "/list": { "get": { "parameters": [ { "in": "query", "name": "type", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "filter", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "hide_search", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "add", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "update", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "List response" } }, "summary": "List id/name/prefix/basename (replacement for get_indexes)", "tags": [ "Browsing, Indexes and Lists" ] } }, "/live-streams": { "get": { "parameters": [ { "in": "query", "name": "filter", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "exact", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "add", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "update", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveStreamsResponse" } } }, "description": "Live stream list" } }, "summary": "List live streams", "tags": [ "Live Streams" ] }, "put": { "parameters": [ { "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "url", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "site_url", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "codec", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "catalog", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Live stream created" } }, "summary": "Create a live stream (radio station)", "tags": [ "Live Streams" ] } }, "/live-streams/{live_stream_id}": { "delete": { "parameters": [ { "in": "path", "name": "live_stream_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Deleted" } }, "summary": "Delete a live stream (radio station)", "tags": [ "Live Streams" ] }, "get": { "parameters": [ { "in": "path", "name": "live_stream_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveStreamObject" } } }, "description": "Live stream object" } }, "summary": "Get live stream by ID", "tags": [ "Live Streams" ] }, "patch": { "parameters": [ { "in": "path", "name": "live_stream_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "url", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "site_url", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "codec", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "catalog", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Live stream updated" } }, "summary": "Edit a live stream (radio station)", "tags": [ "Live Streams" ] } }, "/live-streams/{live_stream_id}/localplay": { "post": { "parameters": [ { "description": "Media object id", "in": "path", "name": "live_stream_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "command", "required": true, "schema": { "enum": [ "add" ], "type": "string" } }, { "in": "query", "name": "type", "required": false, "schema": { "enum": [ "song", "video", "podcast_episode", "channel", "broadcast", "democratic", "live_stream" ], "type": "string" } }, { "in": "query", "name": "clear", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Localplay response" } }, "summary": "Add media to the localplay server", "tags": [ "Playback Control" ] } }, "/localplay/add": { "post": { "parameters": [ { "in": "query", "name": "filter", "description": "Object id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "type", "required": false, "schema": { "enum": [ "song", "video", "podcast_episode" ], "type": "string", "default": "song" } }, { "in": "query", "name": "clear", "description": "Clear the current playlist before adding", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Localplay response" } }, "summary": "Add an object to the localplay server", "tags": [ "Playback Control" ] } }, "/localplay/next": { "post": { "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Localplay response" } }, "summary": "Send next command to localplay", "tags": [ "Playback Control" ] } }, "/localplay/prev": { "post": { "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Localplay response" } }, "summary": "Send previous command to localplay", "tags": [ "Playback Control" ] } }, "/localplay/stop": { "post": { "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Localplay response" } }, "summary": "Send stop command to localplay", "tags": [ "Playback Control" ] } }, "/localplay/play": { "post": { "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Localplay response" } }, "summary": "Send play command to localplay", "tags": [ "Playback Control" ] } }, "/localplay/pause": { "post": { "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Localplay response" } }, "summary": "Send pause command to localplay", "tags": [ "Playback Control" ] } }, "/localplay/volume-up": { "post": { "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Localplay response" } }, "summary": "Send volume up command to localplay", "tags": [ "Playback Control" ] } }, "/localplay/volume-down": { "post": { "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Localplay response" } }, "summary": "Send volume down command to localplay", "tags": [ "Playback Control" ] } }, "/localplay/volume-mute": { "post": { "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Localplay response" } }, "summary": "Send volume mute command to localplay", "tags": [ "Playback Control" ] } }, "/localplay/delete-all": { "post": { "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Localplay response" } }, "summary": "Send delete all command to localplay", "tags": [ "Playback Control" ] } }, "/localplay/skip": { "post": { "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Localplay response" } }, "summary": "Send skip command to localplay", "tags": [ "Playback Control" ] } }, "/localplay/status": { "get": { "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Localplay status response" } }, "summary": "Get localplay status", "tags": [ "Playback Control" ] } }, "/me": { "get": { "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "User array" } }, "summary": "Get information about your own user account", "tags": [ "Users" ] } }, "/me/friends-timeline": { "get": { "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "since", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Activity list" } }, "summary": "Get current user's friends timeline", "tags": [ "Social" ] } }, "/me/last-shouts": { "get": { "parameters": [ { "in": "query", "name": "filter", "required": false, "description": "Username to filter shouts by", "schema": { "type": "string" } }, { "in": "query", "name": "username", "required": false, "schema": { "type": "string" }, "deprecated": true, "description": "Deprecated: use `filter` instead. Removed in API9." }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Shout list" } }, "summary": "Get latest shouts", "tags": [ "Social" ] } }, "/me/lost-password": { "get": { "parameters": [ { "in": "query", "name": "auth", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Success" } }, "summary": "Allows a non-admin user to reset their password without web access to the main site", "tags": [ "Authentication" ] } }, "/me/now-playing": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Now playing list" } }, "summary": "Get what is currently being played by all users", "tags": [ "Now Playing" ] } }, "/me/playlists": { "get": { "parameters": [ { "in": "query", "name": "filter", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "exact", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "include", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "add", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "update", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaylistsResponse" } } }, "description": "Playlist list" } }, "summary": "List playlists for the current user context", "tags": [ "Playlists" ] } }, "/me/smartlists": { "get": { "parameters": [ { "in": "query", "name": "filter", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "exact", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "include", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "add", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "update", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaylistsResponse" } } }, "description": "Smartlist list" } }, "summary": "List smartlists for the current user context", "tags": [ "Playlists" ] } }, "/ping": { "get": { "description": "Does not require authentication. If you provide authentication (auth query/header or Bearer), the server may return additional session and library metadata.", "parameters": [ { "description": "API version the client understands (optional).", "in": "query", "name": "version", "required": false, "schema": { "type": "string" } }, { "description": "Optional session/API key. May extend session and return additional data when provided.", "in": "query", "name": "auth", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } }, "application/xml": { "schema": { "type": "string" } } }, "description": "Ping response (contents may vary based on whether authentication is provided)." } }, "security": [ {}, { "BearerAuth": [] }, { "ApiKeyAuthHeader": [] }, { "ApiKeyAuthQuery": [] } ], "summary": "Ping server and get status/version", "tags": [ "Authentication" ] } }, "/playlists": { "get": { "parameters": [ { "in": "query", "name": "filter", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "hide_search", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "show_dupes", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "exact", "required": false, "schema": { "type": "boolean" } }, { "in": "query", "name": "add", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "update", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaylistsResponse" } } }, "description": "Playlists list" } }, "summary": "List playlists", "tags": [ "Playlists" ] }, "put": { "parameters": [ { "in": "query", "name": "name", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "type", "required": false, "schema": { "enum": [ "public", "private" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Playlist created" } }, "summary": "Create a new playlist", "tags": [ "Playlists" ] } }, "/playlists/{playlist_id}": { "delete": { "parameters": [ { "in": "path", "name": "playlist_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Success" } }, "summary": "Delete a playlist", "tags": [ "Playlists" ] }, "get": { "parameters": [ { "in": "path", "name": "playlist_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaylistObject" } } }, "description": "Playlist response" } }, "summary": "Get a single playlist", "tags": [ "Playlists" ] }, "patch": { "parameters": [ { "in": "path", "name": "playlist_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "type", "required": false, "schema": { "enum": [ "public", "private" ], "type": "string" } }, { "description": "User id (-1 = System playlist)", "in": "query", "name": "owner", "required": false, "schema": { "type": "string" } }, { "description": "Comma-separated song_id list", "in": "query", "name": "items", "required": false, "schema": { "type": "string" } }, { "description": "Comma-separated playlist track numbers matched to items", "in": "query", "name": "tracks", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Success" } }, "summary": "Edit playlist metadata and items", "tags": [ "Playlists" ] } }, "/playlists/{playlist_id}/add": { "post": { "parameters": [ { "in": "path", "name": "playlist_id", "required": true, "schema": { "type": "string" } }, { "description": "UID of the object to add to playlist", "in": "query", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "type", "required": true, "schema": { "enum": [ "song", "album", "artist", "playlist" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Success" } }, "summary": "Add an item to a playlist", "tags": [ "Playlists" ] } }, "/playlists/{playlist_id}/art": { "get": { "parameters": [ { "in": "path", "name": "playlist_id", "required": true, "schema": { "type": "string" } }, { "description": "widthxheight, e.g. 640x480", "in": "query", "name": "size", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Binary image response" } }, "summary": "Get art image (binary)", "tags": [ "Artwork" ] } }, "/playlists/{playlist_id}/download": { "get": { "parameters": [ { "in": "path", "name": "playlist_id", "required": true, "schema": { "type": "string" } }, { "description": "Max bitrate for transcoding in bits per second (e.g 192000 = 192Kb)", "in": "query", "name": "bitrate", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "format", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "stats", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "description": "Binary file response" }, "416": { "description": "Range not satisfiable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Download a media file (binary)", "tags": [ "Streaming and Downloads" ] } }, "/playlists/{playlist_id}/flag": { "post": { "parameters": [ { "in": "path", "name": "playlist_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "flag", "required": true, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Updated" } }, "summary": "Flag or unflag an item as favourite", "tags": [ "Ratings and Flags" ] } }, "/playlists/{playlist_id}/hash": { "get": { "parameters": [ { "in": "path", "name": "playlist_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "md5": { "type": "string" } }, "type": "object" } } }, "description": "MD5 response" } }, "summary": "Get MD5 hash for playlist songs", "tags": [ "Playlists" ] } }, "/playlists/{playlist_id}/rate": { "post": { "parameters": [ { "in": "path", "name": "playlist_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "rating", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Success" } }, "summary": "Rate a library item", "tags": [ "Ratings and Flags" ] } }, "/playlists/{playlist_id}/remove-song": { "post": { "parameters": [ { "in": "path", "name": "playlist_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "song", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "track", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Success" } }, "summary": "Remove a song (or track) from a playlist", "tags": [ "Playlists" ] } }, "/playlists/{playlist_id}/share": { "post": { "parameters": [ { "description": "UID of object you are sharing", "in": "path", "name": "playlist_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "description", "required": false, "schema": { "type": "string" } }, { "description": "days to keep active", "in": "query", "name": "expires", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Share created" } }, "summary": "Create a public share URL", "tags": [ "Shares" ] } }, "/playlists/{playlist_id}/songs": { "get": { "parameters": [ { "in": "path", "name": "playlist_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "random", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SongsResponse" } } }, "description": "Song list" } }, "summary": "Get songs for a playlist", "tags": [ "Playlists", "Songs" ] } }, "/playlists/{playlist_id}/stream": { "get": { "parameters": [ { "in": "path", "name": "playlist_id", "required": true, "schema": { "type": "string" } }, { "description": "Max bitrate for transcoding in bits per second (e.g 192000 = 192Kb)", "in": "query", "name": "bitrate", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "format", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "length", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "stats", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "description": "Binary stream response" }, "416": { "description": "Range not satisfiable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Stream a media file (binary)", "tags": [ "Streaming and Downloads" ] } }, "/playlists/search": { "get": { "description": "Provide operator plus one or more rule triplets. At minimum, rule_1, rule_1_operator, rule_1_input are required. Additional rules may be supplied as rule_2, rule_2_operator, rule_2_input, etc.", "operationId": "playlist-search", "parameters": [ { "description": "and, or (whether to match one rule or all)", "in": "query", "name": "operator", "required": true, "schema": { "enum": [ "and", "or" ], "type": "string" } }, { "description": "0, 1 (random order of results; default to 0)", "in": "query", "name": "random", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Return results starting from this index position", "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "type": "integer" } }, { "description": "Maximum number of results to return", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 500, "minimum": 1, "type": "integer" } }, { "description": "Rule field/key for rule 1", "in": "query", "name": "rule_1", "required": true, "schema": { "type": "string" } }, { "description": "Operator for rule 1", "in": "query", "name": "rule_1_operator", "required": true, "schema": { "type": "string" } }, { "description": "Input value for rule 1", "in": "query", "name": "rule_1_input", "required": true, "schema": { "type": "string" } }, { "description": "Rule field/key for rule 2", "in": "query", "name": "rule_2", "required": false, "schema": { "type": "string" } }, { "description": "Operator for rule 2", "in": "query", "name": "rule_2_operator", "required": false, "schema": { "type": "string" } }, { "description": "Input value for rule 2", "in": "query", "name": "rule_2_input", "required": false, "schema": { "type": "string" } }, { "description": "Rule field/key for rule 3", "in": "query", "name": "rule_3", "required": false, "schema": { "type": "string" } }, { "description": "Operator for rule 3", "in": "query", "name": "rule_3_operator", "required": false, "schema": { "type": "string" } }, { "description": "Input value for rule 3", "in": "query", "name": "rule_3_input", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Search results" } }, "summary": "Search for media entities using rule triplets", "tags": [ "Playlists", "Search" ] } }, "/playlists/stats": { "get": { "parameters": [ { "description": "newest, highest, frequent, recent, forgotten, flagged, random", "in": "query", "name": "filter", "required": true, "schema": { "default": "random", "enum": [ "newest", "highest", "frequent", "recent", "forgotten", "flagged", "random" ], "type": "string" } }, { "in": "query", "name": "user_id", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "username", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Stats result" } }, "summary": "Get stats (song/album/artist etc) by type and filter", "tags": [ "Browsing, Indexes and Lists" ] } }, "/podcast-episodes": { "get": { "parameters": [ { "in": "query", "name": "filter", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastEpisodesResponse" } } }, "description": "Podcast Episode list" } }, "summary": "List podcast episodes", "tags": [ "Podcasts" ] } }, "/podcast-episodes/{episode_id}": { "delete": { "parameters": [ { "in": "path", "name": "episode_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Deleted" } }, "summary": "Delete a podcast episode", "tags": [ "Podcasts" ] }, "get": { "parameters": [ { "in": "path", "name": "episode_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastEpisodeObject" } } }, "description": "Podcast episode object" } }, "summary": "Get podcast episode by ID", "tags": [ "Podcasts" ] } }, "/podcast-episodes/{episode_id}/bookmark": { "delete": { "parameters": [ { "description": "episode_id", "in": "path", "name": "episode_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "client", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Success" } }, "summary": "Delete a bookmark", "tags": [ "Bookmarks" ] }, "get": { "parameters": [ { "in": "path", "name": "episode_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "include", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Bookmark object" } }, "summary": "Get bookmark by ID", "tags": [ "Bookmarks" ] }, "patch": { "parameters": [ { "description": "episode_id", "in": "path", "name": "episode_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "position", "required": true, "schema": { "type": "integer" } }, { "in": "query", "name": "client", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "date", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "include", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Bookmark array" } }, "summary": "Edit a bookmark", "tags": [ "Bookmarks" ] }, "put": { "parameters": [ { "description": "episode_id", "in": "path", "name": "episode_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "position", "required": true, "schema": { "type": "integer" } }, { "in": "query", "name": "client", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "date", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "include", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Bookmark object" } }, "summary": "Create a bookmark", "tags": [ "Bookmarks" ] } }, "/podcast-episodes/{episode_id}/download": { "get": { "parameters": [ { "in": "path", "name": "episode_id", "required": true, "schema": { "type": "string" } }, { "description": "Max bitrate for transcoding in bits per second (e.g 192000 = 192Kb)", "in": "query", "name": "bitrate", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "format", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "stats", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "description": "Binary file response" }, "416": { "description": "Range not satisfiable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Download a media file (binary)", "tags": [ "Streaming and Downloads" ] } }, "/podcast-episodes/{episode_id}/flag": { "post": { "parameters": [ { "in": "path", "name": "episode_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "flag", "required": true, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Updated" } }, "summary": "Flag or unflag an item as favourite", "tags": [ "Ratings and Flags" ] } }, "/podcast-episodes/{episode_id}/localplay": { "post": { "parameters": [ { "description": "Media object id", "in": "path", "name": "episode_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "command", "required": true, "schema": { "enum": [ "add" ], "type": "string" } }, { "in": "query", "name": "type", "required": false, "schema": { "enum": [ "song", "video", "podcast_episode", "channel", "broadcast", "democratic", "live_stream" ], "type": "string" } }, { "in": "query", "name": "clear", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Localplay response" } }, "summary": "Add media to the localplay server", "tags": [ "Playback Control" ] } }, "/podcast-episodes/{episode_id}/playback": { "post": { "parameters": [ { "in": "path", "name": "episode_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "type", "required": false, "schema": { "enum": [ "song", "video", "podcast_episode" ], "type": "string" } }, { "in": "query", "name": "state", "required": false, "schema": { "enum": [ "play", "stop" ], "type": "string" } }, { "in": "query", "name": "time", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "client", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Now playing response" } }, "summary": "Update the server with the client player state", "tags": [ "Now Playing" ] } }, "/podcast-episodes/{episode_id}/rate": { "post": { "parameters": [ { "in": "path", "name": "episode_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "rating", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Success" } }, "summary": "Rate a library item", "tags": [ "Ratings and Flags" ] } }, "/podcast-episodes/{episode_id}/share": { "post": { "parameters": [ { "description": "UID of object you are sharing", "in": "path", "name": "episode_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "description", "required": false, "schema": { "type": "string" } }, { "description": "days to keep active", "in": "query", "name": "expires", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Share created" } }, "summary": "Create a public share URL", "tags": [ "Shares" ] } }, "/podcast-episodes/{episode_id}/stream": { "get": { "parameters": [ { "in": "path", "name": "episode_id", "required": true, "schema": { "type": "string" } }, { "description": "Max bitrate for transcoding in bits per second (e.g 192000 = 192Kb)", "in": "query", "name": "bitrate", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "format", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "length", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "stats", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "description": "Binary stream response" }, "416": { "description": "Range not satisfiable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Stream a media file (binary)", "tags": [ "Streaming and Downloads" ] } }, "/podcast-episodes/deleted": { "get": { "parameters": [ { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Deleted podcast episodes list" } }, "summary": "List deleted podcast episodes", "tags": [ "Maintenance" ] } }, "/podcast-episodes/search": { "get": { "description": "Provide operator plus one or more rule triplets. At minimum, rule_1, rule_1_operator, rule_1_input are required. Additional rules may be supplied as rule_2, rule_2_operator, rule_2_input, etc.", "operationId": "podcast-episode-search", "parameters": [ { "description": "and, or (whether to match one rule or all)", "in": "query", "name": "operator", "required": true, "schema": { "enum": [ "and", "or" ], "type": "string" } }, { "description": "0, 1 (random order of results; default to 0)", "in": "query", "name": "random", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Return results starting from this index position", "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "type": "integer" } }, { "description": "Maximum number of results to return", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 500, "minimum": 1, "type": "integer" } }, { "description": "Rule field/key for rule 1", "in": "query", "name": "rule_1", "required": true, "schema": { "type": "string" } }, { "description": "Operator for rule 1", "in": "query", "name": "rule_1_operator", "required": true, "schema": { "type": "string" } }, { "description": "Input value for rule 1", "in": "query", "name": "rule_1_input", "required": true, "schema": { "type": "string" } }, { "description": "Rule field/key for rule 2", "in": "query", "name": "rule_2", "required": false, "schema": { "type": "string" } }, { "description": "Operator for rule 2", "in": "query", "name": "rule_2_operator", "required": false, "schema": { "type": "string" } }, { "description": "Input value for rule 2", "in": "query", "name": "rule_2_input", "required": false, "schema": { "type": "string" } }, { "description": "Rule field/key for rule 3", "in": "query", "name": "rule_3", "required": false, "schema": { "type": "string" } }, { "description": "Operator for rule 3", "in": "query", "name": "rule_3_operator", "required": false, "schema": { "type": "string" } }, { "description": "Input value for rule 3", "in": "query", "name": "rule_3_input", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Search results" } }, "summary": "Search for media entities using rule triplets", "tags": [ "Podcasts", "Search" ] } }, "/podcast-episodes/stats": { "get": { "parameters": [ { "description": "newest, highest, frequent, recent, forgotten, flagged, random", "in": "query", "name": "filter", "required": true, "schema": { "default": "random", "enum": [ "newest", "highest", "frequent", "recent", "forgotten", "flagged", "random" ], "type": "string" } }, { "in": "query", "name": "user_id", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "username", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Stats result" } }, "summary": "Get stats (song/album/artist etc) by type and filter", "tags": [ "Browsing, Indexes and Lists" ] } }, "/podcasts": { "get": { "parameters": [ { "in": "query", "name": "filter", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "include", "required": false, "schema": { "enum": [ "episodes" ], "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastsResponse" } } }, "description": "Podcast list" } }, "summary": "List podcasts", "tags": [ "Podcasts" ] }, "put": { "parameters": [ { "description": "RSS URL for podcast", "in": "query", "name": "url", "required": true, "schema": { "type": "string" } }, { "description": "Podcast catalog ID", "in": "query", "name": "catalog", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Podcast created" } }, "summary": "Create a podcast", "tags": [ "Podcasts" ] } }, "/podcasts/{podcast_id}": { "delete": { "parameters": [ { "in": "path", "name": "podcast_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Deleted" } }, "summary": "Delete a podcast", "tags": [ "Podcasts" ] }, "get": { "parameters": [ { "in": "path", "name": "podcast_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "include", "required": false, "schema": { "enum": [ "episodes" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastObject" } } }, "description": "Podcast object" } }, "summary": "Get podcast by ID", "tags": [ "Podcasts" ] }, "patch": { "parameters": [ { "in": "path", "name": "podcast_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "feed", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "title", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "website", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "description", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "generator", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "copyright", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Updated" } }, "summary": "Edit an existing podcast", "tags": [ "Podcasts" ] } }, "/podcasts/{podcast_id}/art": { "get": { "parameters": [ { "in": "path", "name": "podcast_id", "required": true, "schema": { "type": "string" } }, { "description": "widthxheight, e.g. 640x480", "in": "query", "name": "size", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Binary image response" } }, "summary": "Get art image (binary)", "tags": [ "Artwork" ] } }, "/podcasts/{podcast_id}/flag": { "post": { "parameters": [ { "in": "path", "name": "podcast_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "flag", "required": true, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Updated" } }, "summary": "Flag or unflag an item as favourite", "tags": [ "Ratings and Flags" ] } }, "/podcasts/{podcast_id}/podcast-episodes": { "get": { "parameters": [ { "in": "path", "name": "podcast_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastEpisodesResponse" } } }, "description": "Podcast episode list" } }, "summary": "List episodes for a podcast", "tags": [ "Podcasts" ] } }, "/podcasts/{podcast_id}/rate": { "post": { "parameters": [ { "in": "path", "name": "podcast_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "rating", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Success" } }, "summary": "Rate a library item", "tags": [ "Ratings and Flags" ] } }, "/podcasts/{podcast_id}/share": { "post": { "parameters": [ { "description": "UID of object you are sharing", "in": "path", "name": "podcast_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "description", "required": false, "schema": { "type": "string" } }, { "description": "days to keep active", "in": "query", "name": "expires", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Share created" } }, "summary": "Create a public share URL", "tags": [ "Shares" ] } }, "/podcasts/{podcast_id}/sync": { "post": { "parameters": [ { "description": "Podcast id", "in": "path", "name": "podcast_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Sync started" } }, "summary": "Sync and download new podcast episodes", "tags": [ "Podcasts" ] } }, "/podcasts/search": { "get": { "description": "Provide operator plus one or more rule triplets. At minimum, rule_1, rule_1_operator, rule_1_input are required. Additional rules may be supplied as rule_2, rule_2_operator, rule_2_input, etc.", "operationId": "podcast-search", "parameters": [ { "description": "and, or (whether to match one rule or all)", "in": "query", "name": "operator", "required": true, "schema": { "enum": [ "and", "or" ], "type": "string" } }, { "description": "0, 1 (random order of results; default to 0)", "in": "query", "name": "random", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Return results starting from this index position", "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "type": "integer" } }, { "description": "Maximum number of results to return", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 500, "minimum": 1, "type": "integer" } }, { "description": "Rule field/key for rule 1", "in": "query", "name": "rule_1", "required": true, "schema": { "type": "string" } }, { "description": "Operator for rule 1", "in": "query", "name": "rule_1_operator", "required": true, "schema": { "type": "string" } }, { "description": "Input value for rule 1", "in": "query", "name": "rule_1_input", "required": true, "schema": { "type": "string" } }, { "description": "Rule field/key for rule 2", "in": "query", "name": "rule_2", "required": false, "schema": { "type": "string" } }, { "description": "Operator for rule 2", "in": "query", "name": "rule_2_operator", "required": false, "schema": { "type": "string" } }, { "description": "Input value for rule 2", "in": "query", "name": "rule_2_input", "required": false, "schema": { "type": "string" } }, { "description": "Rule field/key for rule 3", "in": "query", "name": "rule_3", "required": false, "schema": { "type": "string" } }, { "description": "Operator for rule 3", "in": "query", "name": "rule_3_operator", "required": false, "schema": { "type": "string" } }, { "description": "Input value for rule 3", "in": "query", "name": "rule_3_input", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Search results" } }, "summary": "Search for media entities using rule triplets", "tags": [ "Podcasts", "Search" ] } }, "/podcasts/stats": { "get": { "parameters": [ { "description": "newest, highest, frequent, recent, forgotten, flagged, random", "in": "query", "name": "filter", "required": true, "schema": { "default": "random", "enum": [ "newest", "highest", "frequent", "recent", "forgotten", "flagged", "random" ], "type": "string" } }, { "in": "query", "name": "user_id", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "username", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Stats result" } }, "summary": "Get stats (song/album/artist etc) by type and filter", "tags": [ "Browsing, Indexes and Lists" ] } }, "/preferences": { "get": { "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Preference list" } }, "summary": "Get your user preferences", "tags": [ "Preferences" ] }, "put": { "parameters": [ { "description": "Preference name", "in": "query", "name": "filter", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "type", "required": true, "schema": { "enum": [ "boolean", "integer", "string", "special" ], "type": "string" } }, { "description": "Default value (string or integer)", "in": "query", "name": "default", "required": true, "schema": { "type": "string" } }, { "description": "interface,internal,options,playlist,plugins,streaming", "in": "query", "name": "category", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "description", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "subcategory", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Created" } }, "summary": "Create a server preference (Admin)", "tags": [ "Preferences" ] } }, "/preferences/{preference_name}": { "get": { "parameters": [ { "in": "path", "name": "preference_name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Preference array" } }, "summary": "Get a user preference by name", "tags": [ "Preferences" ] }, "delete": { "parameters": [ { "in": "path", "name": "preference_name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Deleted" } }, "summary": "Delete a non-system preference by name (Admin)", "tags": [ "Preferences" ] }, "patch": { "parameters": [ { "in": "path", "name": "preference_name", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "value", "required": true, "schema": { "type": "string" } }, { "description": "Apply to all users (Admin)", "in": "query", "name": "all", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "description": "Set as system default (Admin)", "in": "query", "name": "default", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Updated" } }, "summary": "Edit a preference value", "tags": [ "Preferences" ] } }, "/system-preferences": { "get": { "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Preference list" } }, "summary": "Get your system preferences (Admin)", "tags": [ "Preferences" ] } }, "/system-preferences/{preference_name}": { "get": { "parameters": [ { "in": "path", "name": "preference_name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Preference array" } }, "summary": "Get a server preference by name (Admin)", "tags": [ "Preferences" ] } }, "/register": { "post": { "description": "Does not use authentication. Requires username, password and email.", "parameters": [ { "in": "query", "name": "username", "required": true, "schema": { "type": "string" } }, { "description": "hash('sha256', password) Deprecated: for privacy, send this in a form or JSON request body instead of the query string (query values land in server/proxy logs and browser history). Query-string support will be removed in API9.", "in": "query", "name": "password", "required": true, "schema": { "type": "string" }, "deprecated": true }, { "in": "query", "name": "email", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "fullname", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string" }, "password": { "type": "string", "description": "hash('sha256', password)" }, "email": { "type": "string" }, "fullname": { "type": "string" } }, "required": [ "username", "password", "email" ] } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "username": { "type": "string" }, "password": { "type": "string", "description": "hash('sha256', password)" }, "email": { "type": "string" }, "fullname": { "type": "string" } }, "required": [ "username", "password", "email" ] } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "username": { "type": "string" }, "password": { "type": "string", "description": "hash('sha256', password)" }, "email": { "type": "string" }, "fullname": { "type": "string" } }, "required": [ "username", "password", "email" ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } }, "application/xml": { "schema": { "type": "string" } } }, "description": "Success or error" } }, "security": [ {} ], "summary": "Register as a new user (if allowed)", "tags": [ "Authentication" ] } }, "/scrobble": { "post": { "parameters": [ { "in": "query", "name": "song", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "artist", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "album", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "songmbid", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "artistmbid", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "albummbid", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "date", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "client", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Recorded" } }, "summary": "Find a song by metadata and record a play if found", "tags": [ "Now Playing" ] } }, "/search/{search_type}/groups": { "get": { "parameters": [ { "in": "path", "name": "search_type", "required": true, "schema": { "enum": [ "all", "music", "song_artist", "album_artist", "podcast", "video" ], "type": "string" } }, { "in": "query", "name": "operator", "required": true, "schema": { "enum": [ "and", "or" ], "type": "string" } }, { "in": "query", "name": "random", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "rule_1", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "rule_1_operator", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "rule_1_input", "required": true, "schema": { "type": "string" } }, { "description": "Metadata searches only", "in": "query", "name": "rule_1_subtype", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Search results grouped by type" } }, "summary": "Group search across multiple object types", "tags": [ "Search" ] } }, "/search/{search_type}/rules": { "get": { "parameters": [ { "description": "song, album, song_artist, album_artist, artist, label, playlist, podcast, podcast_episode, genre, user, video", "in": "path", "name": "search_type", "required": true, "schema": { "enum": [ "song", "album", "song_artist", "album_artist", "artist", "label", "playlist", "podcast", "podcast_episode", "genre", "user", "video" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Rules list" } }, "summary": "List valid search rules for a search type", "tags": [ "Search", "Utilities" ] } }, "/shares": { "get": { "parameters": [ { "in": "query", "name": "filter", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "exact", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Share list" } }, "summary": "List shares", "tags": [ "Shares" ] }, "put": { "parameters": [ { "in": "query", "name": "filter", "description": "Object id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "type", "required": true, "schema": { "enum": [ "album", "artist", "playlist", "podcast", "podcast_episode", "song", "video" ], "type": "string" } }, { "in": "query", "name": "description", "description": "Filled in for you if empty", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "expires", "description": "Days to keep active", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Share created" } }, "summary": "Create a share", "tags": [ "Shares" ] } }, "/shares/{share_id}": { "delete": { "parameters": [ { "in": "path", "name": "share_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Deleted" } }, "summary": "Delete a share", "tags": [ "Shares" ] }, "get": { "parameters": [ { "in": "path", "name": "share_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Share object" } }, "summary": "Get share by ID", "tags": [ "Shares" ] }, "patch": { "parameters": [ { "in": "path", "name": "share_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "stream", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "download", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "expires", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "description", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Share updated" } }, "summary": "Edit a share", "tags": [ "Shares" ] } }, "/smartlists": { "get": { "parameters": [ { "in": "query", "name": "filter", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "exact", "required": false, "schema": { "type": "boolean" } }, { "in": "query", "name": "add", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "update", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaylistsResponse" } } }, "description": "Playlists list" } }, "summary": "List smartplaylists", "tags": [ "Playlists" ] } }, "/smartlists/{smartlist_id}": { "delete": { "parameters": [ { "in": "path", "name": "smartlist_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Success" } }, "summary": "Delete a smartlist", "tags": [ "Playlists" ] }, "get": { "parameters": [ { "in": "path", "name": "smartlist_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaylistObject" } } }, "description": "Playlist response" } }, "summary": "Get a single smartplaylist", "tags": [ "Playlists" ] } }, "/smartlists/{smartlist_id}/art": { "get": { "parameters": [ { "in": "path", "name": "smartlist_id", "required": true, "schema": { "type": "string" } }, { "description": "widthxheight, e.g. 640x480", "in": "query", "name": "size", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Binary image response" } }, "summary": "Get art image (binary)", "tags": [ "Artwork" ] } }, "/smartlists/{smartlist_id}/download": { "get": { "parameters": [ { "in": "path", "name": "smartlist_id", "required": true, "schema": { "type": "string" } }, { "description": "Max bitrate for transcoding in bits per second (e.g 192000 = 192Kb)", "in": "query", "name": "bitrate", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "format", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "stats", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "description": "Binary file response" }, "416": { "description": "Range not satisfiable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Download a media file (binary)", "tags": [ "Streaming and Downloads" ] } }, "/smartlists/{smartlist_id}/flag": { "post": { "parameters": [ { "in": "path", "name": "smartlist_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "flag", "required": true, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Updated" } }, "summary": "Flag or unflag an item as favourite", "tags": [ "Ratings and Flags" ] } }, "/smartlists/{smartlist_id}/rate": { "post": { "parameters": [ { "in": "path", "name": "smartlist_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "rating", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Success" } }, "summary": "Rate a library item", "tags": [ "Ratings and Flags" ] } }, "/smartlists/{smartlist_id}/share": { "post": { "parameters": [ { "description": "UID of object you are sharing", "in": "path", "name": "smartlist_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "description", "required": false, "schema": { "type": "string" } }, { "description": "days to keep active", "in": "query", "name": "expires", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Share created" } }, "summary": "Create a public share URL", "tags": [ "Shares" ] } }, "/smartlists/{smartlist_id}/songs": { "get": { "parameters": [ { "in": "path", "name": "smartlist_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "random", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SongsResponse" } } }, "description": "Song list" } }, "summary": "Get songs for a smartlist", "tags": [ "Playlists", "Songs" ] } }, "/smartlists/{smartlist_id}/stream": { "get": { "parameters": [ { "in": "path", "name": "smartlist_id", "required": true, "schema": { "type": "string" } }, { "description": "Max bitrate for transcoding in bits per second (e.g 192000 = 192Kb)", "in": "query", "name": "bitrate", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "format", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "length", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "stats", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "description": "Binary stream response" }, "416": { "description": "Range not satisfiable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Stream a media file (binary)", "tags": [ "Streaming and Downloads" ] } }, "/songs": { "get": { "parameters": [ { "in": "query", "name": "filter", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "exact", "required": false, "schema": { "type": "boolean" } }, { "in": "query", "name": "add", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "update", "required": false, "schema": { "format": "date", "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SongsResponse" } } }, "description": "Songs list" } }, "summary": "List songs", "tags": [ "Songs" ] } }, "/songs/{song_id}": { "delete": { "parameters": [ { "in": "path", "name": "song_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Deleted" } }, "summary": "Delete a song", "tags": [ "Songs" ] }, "get": { "parameters": [ { "in": "path", "name": "song_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SongObject" } } }, "description": "Song details" } }, "summary": "Get song by ID", "tags": [ "Songs" ] } }, "/songs/{song_id}/art": { "get": { "parameters": [ { "in": "path", "name": "song_id", "required": true, "schema": { "type": "string" } }, { "description": "widthxheight, e.g. 640x480", "in": "query", "name": "size", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Binary image response" } }, "summary": "Get art image (binary)", "tags": [ "Artwork" ] } }, "/songs/{song_id}/bookmark": { "delete": { "parameters": [ { "description": "song_id", "in": "path", "name": "song_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "client", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Success" } }, "summary": "Delete a bookmark", "tags": [ "Bookmarks" ] }, "get": { "parameters": [ { "in": "path", "name": "song_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "include", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Bookmark object" } }, "summary": "Get bookmark by ID", "tags": [ "Bookmarks" ] }, "patch": { "parameters": [ { "description": "song_id", "in": "path", "name": "song_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "position", "required": true, "schema": { "type": "integer" } }, { "in": "query", "name": "client", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "date", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "include", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Bookmark array" } }, "summary": "Edit a bookmark", "tags": [ "Bookmarks" ] }, "put": { "parameters": [ { "description": "song_id", "in": "path", "name": "song_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "position", "required": true, "schema": { "type": "integer" } }, { "in": "query", "name": "client", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "date", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "include", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Bookmark object" } }, "summary": "Create a bookmark", "tags": [ "Bookmarks" ] } }, "/songs/{song_id}/download": { "get": { "parameters": [ { "in": "path", "name": "song_id", "required": true, "schema": { "type": "string" } }, { "description": "Max bitrate for transcoding in bits per second (e.g 192000 = 192Kb)", "in": "query", "name": "bitrate", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "format", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "stats", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "description": "Binary file response" }, "416": { "description": "Range not satisfiable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Download a media file (binary)", "tags": [ "Streaming and Downloads" ] } }, "/songs/{song_id}/fetch-metadata": { "get": { "parameters": [ { "in": "path", "name": "song_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "External metadata array" } }, "summary": "Get external metadata for a song", "tags": [ "Songs", "Utilities" ] } }, "/songs/{song_id}/flag": { "post": { "parameters": [ { "in": "path", "name": "song_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "flag", "required": true, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Updated" } }, "summary": "Flag or unflag an item as favourite", "tags": [ "Ratings and Flags" ] } }, "/songs/{song_id}/localplay": { "post": { "parameters": [ { "description": "Media object id", "in": "path", "name": "song_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "command", "required": true, "schema": { "enum": [ "add" ], "type": "string" } }, { "in": "query", "name": "type", "required": false, "schema": { "enum": [ "song", "video", "podcast_episode", "channel", "broadcast", "democratic", "live_stream" ], "type": "string" } }, { "in": "query", "name": "clear", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Localplay response" } }, "summary": "Add media to the localplay server", "tags": [ "Playback Control" ] } }, "/songs/{song_id}/lyrics": { "get": { "parameters": [ { "in": "path", "name": "song_id", "required": true, "schema": { "type": "string" } }, { "description": "Disable plugin lookup if 0 (default 1)", "in": "query", "name": "plugins", "required": true, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Lyrics/plugins response" } }, "summary": "Get lyrics from DB or plugins by song id", "tags": [ "Songs", "Utilities" ] } }, "/songs/{song_id}/playback": { "post": { "parameters": [ { "in": "path", "name": "song_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "type", "required": false, "schema": { "enum": [ "song", "video", "podcast_episode" ], "type": "string" } }, { "in": "query", "name": "state", "required": false, "schema": { "enum": [ "play", "stop" ], "type": "string" } }, { "in": "query", "name": "time", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "client", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Now playing response" } }, "summary": "Update the server with the client player state", "tags": [ "Now Playing" ] } }, "/songs/{song_id}/rate": { "post": { "parameters": [ { "in": "path", "name": "song_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "rating", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Success" } }, "summary": "Rate a library item", "tags": [ "Ratings and Flags" ] } }, "/songs/{song_id}/record-play": { "post": { "parameters": [ { "in": "path", "name": "song_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "user", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "client", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "date", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Recorded" } }, "summary": "Record a play for a song", "tags": [ "Now Playing" ] } }, "/songs/{song_id}/share": { "post": { "parameters": [ { "description": "UID of object you are sharing", "in": "path", "name": "song_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "description", "required": false, "schema": { "type": "string" } }, { "description": "days to keep active", "in": "query", "name": "expires", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Share created" } }, "summary": "Create a public share URL", "tags": [ "Shares" ] } }, "/songs/{song_id}/similar": { "get": { "parameters": [ { "in": "path", "name": "song_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Similar list" } }, "summary": "Get similar songs", "tags": [ "Songs" ] } }, "/songs/{song_id}/stream": { "get": { "parameters": [ { "in": "path", "name": "song_id", "required": true, "schema": { "type": "string" } }, { "description": "Max bitrate for transcoding in bits per second (e.g 192000 = 192Kb)", "in": "query", "name": "bitrate", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "format", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "length", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "stats", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "description": "Binary stream response" }, "416": { "description": "Range not satisfiable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Stream a media file (binary)", "tags": [ "Streaming and Downloads" ] } }, "/songs/{song_id}/tags": { "get": { "parameters": [ { "in": "path", "name": "song_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Song tags" } }, "summary": "Get full file tags for a song", "tags": [ "Songs", "Utilities" ] } }, "/songs/{song_id}/update-tags": { "post": { "parameters": [ { "in": "path", "name": "song_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Updated" } }, "summary": "Update object metadata from tags", "tags": [ "Utilities" ] } }, "/songs/deleted": { "get": { "parameters": [ { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Deleted songs list" } }, "summary": "List deleted songs", "tags": [ "Maintenance" ] } }, "/songs/lookup/url-to-song": { "get": { "parameters": [ { "in": "query", "name": "filter", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Song object" } }, "summary": "Convert an Ampache URL back to a song object", "tags": [ "Utilities" ] } }, "/songs/playlist-generate": { "get": { "parameters": [ { "in": "query", "name": "mode", "required": false, "schema": { "enum": [ "recent", "forgotten", "unplayed", "random" ], "type": "string" } }, { "description": "LIKE match to song title", "in": "query", "name": "filter", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "album", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "artist", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "flag", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "format", "required": false, "schema": { "enum": [ "song", "index", "id" ], "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "type": "array", "items": { "type": "string" } } ] } } }, "description": "Generated list" } }, "summary": "Generate a playlist result set (song, index, or id)", "tags": [ "Playlists" ] } }, "/songs/search": { "get": { "description": "Provide operator plus one or more rule triplets. At minimum, rule_1, rule_1_operator, rule_1_input are required. Additional rules may be supplied as rule_2, rule_2_operator, rule_2_input, etc.", "operationId": "song-search", "parameters": [ { "description": "and, or (whether to match one rule or all)", "in": "query", "name": "operator", "required": true, "schema": { "enum": [ "and", "or" ], "type": "string" } }, { "description": "0, 1 (random order of results; default to 0)", "in": "query", "name": "random", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Return results starting from this index position", "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "type": "integer" } }, { "description": "Maximum number of results to return", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 500, "minimum": 1, "type": "integer" } }, { "description": "Rule field/key for rule 1", "in": "query", "name": "rule_1", "required": true, "schema": { "type": "string" } }, { "description": "Operator for rule 1", "in": "query", "name": "rule_1_operator", "required": true, "schema": { "type": "string" } }, { "description": "Input value for rule 1", "in": "query", "name": "rule_1_input", "required": true, "schema": { "type": "string" } }, { "description": "Rule field/key for rule 2", "in": "query", "name": "rule_2", "required": false, "schema": { "type": "string" } }, { "description": "Operator for rule 2", "in": "query", "name": "rule_2_operator", "required": false, "schema": { "type": "string" } }, { "description": "Input value for rule 2", "in": "query", "name": "rule_2_input", "required": false, "schema": { "type": "string" } }, { "description": "Rule field/key for rule 3", "in": "query", "name": "rule_3", "required": false, "schema": { "type": "string" } }, { "description": "Operator for rule 3", "in": "query", "name": "rule_3_operator", "required": false, "schema": { "type": "string" } }, { "description": "Input value for rule 3", "in": "query", "name": "rule_3_input", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Search results" } }, "summary": "Search for media entities using rule triplets", "tags": [ "Songs", "Search" ] } }, "/songs/stats": { "get": { "parameters": [ { "description": "newest, highest, frequent, recent, forgotten, flagged, random", "in": "query", "name": "filter", "required": true, "schema": { "default": "random", "enum": [ "newest", "highest", "frequent", "recent", "forgotten", "flagged", "random" ], "type": "string" } }, { "in": "query", "name": "user_id", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "username", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Stats result" } }, "summary": "Get stats (song/album/artist etc) by type and filter", "tags": [ "Browsing, Indexes and Lists" ] } }, "/update": { "get": { "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Update Ampache" } }, "summary": "Get information about your own user account", "tags": [ "Maintenance" ] } }, "/users": { "get": { "parameters": [ { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsersResponse" } } }, "description": "User list" } }, "summary": "List user ID's and Usernames for your site", "tags": [ "Users" ] }, "put": { "parameters": [ { "in": "query", "name": "username", "required": true, "schema": { "type": "string" } }, { "description": "sha256(password) Deprecated: for privacy, send this in a form or JSON request body instead of the query string (query values land in server/proxy logs and browser history). Query-string support will be removed in API9.", "in": "query", "name": "password", "required": true, "schema": { "type": "string" }, "deprecated": true }, { "in": "query", "name": "email", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "fullname", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "disable", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "group", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Created" } }, "summary": "Create a new user (Admin)", "tags": [ "Users" ] } }, "/users/{user_id}": { "delete": { "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Deleted" } }, "summary": "Delete a user (Admin)", "tags": [ "Users" ] }, "get": { "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "User array" } }, "summary": "Get a user's public information by username", "tags": [ "Users" ] }, "patch": { "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "type": "integer" } }, { "in": "query", "name": "password", "required": false, "schema": { "type": "string" }, "deprecated": true, "description": "Deprecated: for privacy, send this in a form or JSON request body instead of the query string (query values land in server/proxy logs and browser history). Query-string support will be removed in API9." }, { "in": "query", "name": "email", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "fullname", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "website", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "state", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "city", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "disable", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "group", "required": false, "schema": { "type": "integer" } }, { "description": "Maximum transcode bitrate for the user, in kbps (e.g 320). API8 takes this value in bits per second.", "in": "query", "name": "maxbitrate", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "fullname_public", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "reset_apikey", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "reset_streamtoken", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "clear_stats", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Updated" } }, "summary": "Edit a user (Admin)", "tags": [ "Users" ] } }, "/users/{user_id}/follow": { "post": { "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Success" } }, "summary": "Follow or unfollow a user (toggle)", "tags": [ "Social" ] } }, "/users/{user_id}/followers": { "get": { "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "User list" } }, "summary": "Get followers for a username", "tags": [ "Social" ] } }, "/users/{user_id}/following": { "get": { "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "User list" } }, "summary": "Get who a user is following", "tags": [ "Social" ] } }, "/users/{user_id}/timeline": { "get": { "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "since", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Timeline activity list" } }, "summary": "Get a user's timeline", "tags": [ "Social" ] } }, "/users/search": { "get": { "description": "Provide operator plus one or more rule triplets. At minimum, rule_1, rule_1_operator, rule_1_input are required. Additional rules may be supplied as rule_2, rule_2_operator, rule_2_input, etc.", "operationId": "user-search", "parameters": [ { "description": "and, or (whether to match one rule or all)", "in": "query", "name": "operator", "required": true, "schema": { "enum": [ "and", "or" ], "type": "string" } }, { "description": "0, 1 (random order of results; default to 0)", "in": "query", "name": "random", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Return results starting from this index position", "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "type": "integer" } }, { "description": "Maximum number of results to return", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 500, "minimum": 1, "type": "integer" } }, { "description": "Rule field/key for rule 1", "in": "query", "name": "rule_1", "required": true, "schema": { "type": "string" } }, { "description": "Operator for rule 1", "in": "query", "name": "rule_1_operator", "required": true, "schema": { "type": "string" } }, { "description": "Input value for rule 1", "in": "query", "name": "rule_1_input", "required": true, "schema": { "type": "string" } }, { "description": "Rule field/key for rule 2", "in": "query", "name": "rule_2", "required": false, "schema": { "type": "string" } }, { "description": "Operator for rule 2", "in": "query", "name": "rule_2_operator", "required": false, "schema": { "type": "string" } }, { "description": "Input value for rule 2", "in": "query", "name": "rule_2_input", "required": false, "schema": { "type": "string" } }, { "description": "Rule field/key for rule 3", "in": "query", "name": "rule_3", "required": false, "schema": { "type": "string" } }, { "description": "Operator for rule 3", "in": "query", "name": "rule_3_operator", "required": false, "schema": { "type": "string" } }, { "description": "Input value for rule 3", "in": "query", "name": "rule_3_input", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Search results" } }, "summary": "Search for media entities using rule triplets", "tags": [ "Users", "Search" ] } }, "/videos": { "get": { "parameters": [ { "in": "query", "name": "filter", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "exact", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideosResponse" } } }, "description": "Video list" } }, "summary": "List videos", "tags": [ "Videos" ] } }, "/videos/{video_id}": { "get": { "parameters": [ { "in": "path", "name": "video_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoObject" } } }, "description": "Video object" } }, "summary": "Get video by ID", "tags": [ "Videos" ] } }, "/videos/{video_id}/bookmark": { "delete": { "parameters": [ { "description": "video_id", "in": "path", "name": "video_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "client", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Success" } }, "summary": "Delete a bookmark", "tags": [ "Bookmarks" ] }, "get": { "parameters": [ { "in": "path", "name": "video_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "include", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Bookmark object" } }, "summary": "Get bookmark by ID", "tags": [ "Bookmarks" ] }, "patch": { "parameters": [ { "description": "video_id", "in": "path", "name": "video_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "position", "required": true, "schema": { "type": "integer" } }, { "in": "query", "name": "client", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "date", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "include", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Bookmark array" } }, "summary": "Edit a bookmark", "tags": [ "Bookmarks" ] }, "put": { "parameters": [ { "description": "video_id", "in": "path", "name": "video_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "position", "required": true, "schema": { "type": "integer" } }, { "in": "query", "name": "client", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "date", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "include", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Bookmark object" } }, "summary": "Create a bookmark", "tags": [ "Bookmarks" ] } }, "/videos/{video_id}/flag": { "post": { "parameters": [ { "in": "path", "name": "video_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "flag", "required": true, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Updated" } }, "summary": "Flag or unflag an item as favourite", "tags": [ "Ratings and Flags" ] } }, "/videos/{video_id}/localplay": { "post": { "parameters": [ { "description": "Media object id", "in": "path", "name": "video_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "command", "required": true, "schema": { "enum": [ "add" ], "type": "string" } }, { "in": "query", "name": "type", "required": false, "schema": { "enum": [ "song", "video", "podcast_episode", "channel", "broadcast", "democratic", "live_stream" ], "type": "string" } }, { "in": "query", "name": "clear", "required": false, "schema": { "enum": [ 0, 1 ], "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Localplay response" } }, "summary": "Add media to the localplay server", "tags": [ "Playback Control" ] } }, "/videos/{video_id}/playback": { "post": { "parameters": [ { "in": "path", "name": "video_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "type", "required": false, "schema": { "enum": [ "song", "video", "podcast_episode" ], "type": "string" } }, { "in": "query", "name": "state", "required": false, "schema": { "enum": [ "play", "stop" ], "type": "string" } }, { "in": "query", "name": "time", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "client", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Now playing response" } }, "summary": "Update the server with the client player state", "tags": [ "Now Playing" ] } }, "/videos/{video_id}/rate": { "post": { "parameters": [ { "in": "path", "name": "video_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "rating", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Success" } }, "summary": "Rate a library item", "tags": [ "Ratings and Flags" ] } }, "/videos/{video_id}/share": { "post": { "parameters": [ { "description": "UID of object you are sharing", "in": "path", "name": "video_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "description", "required": false, "schema": { "type": "string" } }, { "description": "days to keep active", "in": "query", "name": "expires", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Share created" } }, "summary": "Create a public share URL", "tags": [ "Shares" ] } }, "/videos/deleted": { "get": { "parameters": [ { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Deleted videos list" } }, "summary": "List deleted videos", "tags": [ "Maintenance" ] } }, "/videos/search": { "get": { "description": "Provide operator plus one or more rule triplets. At minimum, rule_1, rule_1_operator, rule_1_input are required. Additional rules may be supplied as rule_2, rule_2_operator, rule_2_input, etc.", "operationId": "video-search", "parameters": [ { "description": "and, or (whether to match one rule or all)", "in": "query", "name": "operator", "required": true, "schema": { "enum": [ "and", "or" ], "type": "string" } }, { "description": "0, 1 (random order of results; default to 0)", "in": "query", "name": "random", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Return results starting from this index position", "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "type": "integer" } }, { "description": "Maximum number of results to return", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 500, "minimum": 1, "type": "integer" } }, { "description": "Rule field/key for rule 1", "in": "query", "name": "rule_1", "required": true, "schema": { "type": "string" } }, { "description": "Operator for rule 1", "in": "query", "name": "rule_1_operator", "required": true, "schema": { "type": "string" } }, { "description": "Input value for rule 1", "in": "query", "name": "rule_1_input", "required": true, "schema": { "type": "string" } }, { "description": "Rule field/key for rule 2", "in": "query", "name": "rule_2", "required": false, "schema": { "type": "string" } }, { "description": "Operator for rule 2", "in": "query", "name": "rule_2_operator", "required": false, "schema": { "type": "string" } }, { "description": "Input value for rule 2", "in": "query", "name": "rule_2_input", "required": false, "schema": { "type": "string" } }, { "description": "Rule field/key for rule 3", "in": "query", "name": "rule_3", "required": false, "schema": { "type": "string" } }, { "description": "Operator for rule 3", "in": "query", "name": "rule_3_operator", "required": false, "schema": { "type": "string" } }, { "description": "Input value for rule 3", "in": "query", "name": "rule_3_input", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Search results" } }, "summary": "Search for media entities using rule triplets", "tags": [ "Videos", "Search" ] } }, "/videos/stats": { "get": { "parameters": [ { "description": "newest, highest, frequent, recent, forgotten, flagged, random", "in": "query", "name": "filter", "required": true, "schema": { "default": "random", "enum": [ "newest", "highest", "frequent", "recent", "forgotten", "flagged", "random" ], "type": "string" } }, { "in": "query", "name": "user_id", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "username", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "cond", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Stats result" } }, "summary": "Get stats (song/album/artist etc) by type and filter", "tags": [ "Browsing, Indexes and Lists" ] } } } }