{
"openapi": "3.0.0",
"info": {
"description": "",
"version": "8.0",
"title": "Polaris",
"termsOfService": ""
},
"servers": [
{
"url": "/api"
}
],
"tags": [
{
"name": "Collection",
"description": "Browsing the music collection"
},
{
"name": "Configuration",
"description": "Managing the polaris installation"
},
{
"name": "Last.fm",
"description": "Integrating with Last.fm"
},
{
"name": "Playlists",
"description": "Managing playlists"
},
{
"name": "Users",
"description": "Managing user accounts"
},
{
"name": "Other"
}
],
"paths": {
"/version": {
"get": {
"tags": [
"Other"
],
"summary": "Returns which API version this server implements",
"operationId": "getVersion",
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Version"
}
}
}
}
}
}
},
"/initial_setup": {
"get": {
"tags": [
"Other"
],
"summary": "Returns the current state of the initial setup flow",
"operationId": "getInitialSetup",
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitialSetup"
}
}
}
}
}
}
},
"/trigger_index": {
"post": {
"tags": [
"Other"
],
"summary": "Begins or queues a crawl of the music collection",
"operationId": "postTriggerIndex",
"responses": {
"200": {
"description": "Successful operation"
}
},
"security": [
{
"admin_http_bearer": [],
"admin_query_parameter": []
}
]
}
},
"/mount_dirs": {
"get": {
"tags": [
"Configuration"
],
"summary": "Reads the existing collection mount directories",
"operationId": "getMountDirs",
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"$ref": "#components/schemas/MountDir"
}
}
}
}
},
"security": [
{
"admin_http_bearer": [],
"admin_query_parameter": []
}
]
},
"put": {
"tags": [
"Configuration"
],
"summary": "Replaces the list collection mount directories",
"operationId": "putMountDirs",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "array",
"$ref": "#components/schemas/MountDir"
}
}
}
},
"responses": {
"200": {
"description": "Successful operation"
}
},
"security": [
{
"admin_http_bearer": [],
"admin_query_parameter": []
}
]
}
},
"/settings": {
"get": {
"tags": [
"Configuration"
],
"summary": "Reads the existing server settings",
"operationId": "getSettings",
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#components/schemas/Settings"
}
}
}
}
},
"security": [
{
"admin_http_bearer": [],
"admin_query_parameter": []
}
]
},
"put": {
"tags": [
"Configuration"
],
"summary": "Amends the server settings",
"operationId": "putSettings",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#components/schemas/Settings"
}
}
}
},
"responses": {
"200": {
"description": "Successful operation"
}
},
"security": [
{
"admin_http_bearer": [],
"admin_query_parameter": []
}
]
}
},
"/users": {
"get": {
"tags": [
"Users"
],
"summary": "List existing user accounts",
"operationId": "getUsers",
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/User"
}
}
}
}
}
},
"security": [
{
"admin_http_bearer": [],
"admin_query_parameter": []
}
]
}
},
"/user": {
"post": {
"tags": [
"Users"
],
"summary": "Creates a new user account",
"operationId": "postUser",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#components/schemas/NewUser"
}
}
}
},
"responses": {
"200": {
"description": "Successful operation"
}
},
"security": [
{
"admin_http_bearer": [],
"admin_query_parameter": []
}
]
}
},
"/user/{name}": {
"put": {
"tags": [
"Users"
],
"summary": "Updates properties of an existing user",
"operationId": "putUserName",
"parameters": [
{
"name": "name",
"in": "path",
"description": "Name of the affected user",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#components/schemas/UserUpdate"
}
}
}
},
"responses": {
"200": {
"description": "Successful operation"
}
},
"security": [
{
"admin_http_bearer": [],
"admin_query_parameter": []
}
]
},
"delete": {
"tags": [
"Users"
],
"summary": "Deletes an existing user",
"operationId": "deleteUserName",
"parameters": [
{
"name": "name",
"in": "path",
"description": "Name of the affected user",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful operation"
}
},
"security": [
{
"admin_http_bearer": [],
"admin_query_parameter": []
}
]
}
},
"/preferences": {
"get": {
"tags": [
"Users"
],
"summary": "Reads the preferences of the current user",
"operationId": "getPreferences",
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#components/schemas/Preferences"
}
}
}
}
},
"security": [
{
"auth_http_bearer": [],
"auth_query_parameter": []
}
]
},
"put": {
"tags": [
"Users"
],
"summary": "Saves the preferences of the current user",
"operationId": "putPreferences",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#components/schemas/Preferences"
}
}
}
},
"responses": {
"200": {
"description": "Successful operation"
}
},
"security": [
{
"auth_http_bearer": [],
"auth_query_parameter": []
}
]
}
},
"/auth": {
"post": {
"tags": [
"Users"
],
"summary": "Signs in a user.",
"operationId": "postAuth",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#components/schemas/Credentials"
}
}
}
},
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Authorization"
}
}
}
},
"401": {
"description": "Invalid credentials"
}
}
}
},
"/browse": {
"get": {
"tags": [
"Collection"
],
"summary": "Reads the content of the top-level directory in the music collection",
"operationId": "getBrowse",
"parameters": [
{
"$ref": "#/components/parameters/APIVersion"
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CollectionFile"
}
}
}
}
}
},
"security": [
{
"auth_http_bearer": [],
"auth_query_parameter": []
}
]
}
},
"/browse/{location}": {
"get": {
"tags": [
"Collection"
],
"summary": "Reads the content of a directory in the music collection",
"operationId": "getBrowsePath",
"parameters": [
{
"name": "location",
"in": "path",
"description": "Path to the collection directory begin explored",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/APIVersion"
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CollectionFile"
}
}
}
}
}
},
"security": [
{
"auth_http_bearer": [],
"auth_query_parameter": []
}
]
}
},
"/flatten": {
"get": {
"tags": [
"Collection"
],
"summary": "Recursively lists all the songs in the music collection",
"operationId": "getFlatten",
"parameters": [
{
"$ref": "#/components/parameters/APIVersion"
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Song"
}
}
}
}
}
},
"security": [
{
"auth_http_bearer": [],
"auth_query_parameter": []
}
]
}
},
"/flatten/{location}": {
"get": {
"tags": [
"Collection"
],
"summary": "Recursively lists all the songs within a directory of the music collection",
"operationId": "getFlattenPath",
"parameters": [
{
"name": "location",
"in": "path",
"description": "Path to the collection directory begin explored",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/APIVersion"
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Song"
}
}
}
}
}
},
"security": [
{
"auth_http_bearer": [],
"auth_query_parameter": []
}
]
}
},
"/random": {
"get": {
"tags": [
"Collection"
],
"summary": "Returns a list of random albums",
"operationId": "getRandom",
"parameters": [
{
"$ref": "#/components/parameters/APIVersion"
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Directory"
}
}
}
}
}
},
"security": [
{
"auth_http_bearer": [],
"auth_query_parameter": []
}
]
}
},
"/recent": {
"get": {
"tags": [
"Collection"
],
"summary": "Returns the albums most recently added to the collection",
"operationId": "getRecent",
"parameters": [
{
"$ref": "#/components/parameters/APIVersion"
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Directory"
}
}
}
}
}
},
"security": [
{
"auth_http_bearer": [],
"auth_query_parameter": []
}
]
}
},
"/search/{query}": {
"get": {
"tags": [
"Collection"
],
"summary": "Searches for songs and directories",
"operationId": "getSearch",
"parameters": [
{
"name": "query",
"in": "path",
"description": "Search query used to filter results",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/APIVersion"
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CollectionFile"
}
}
}
}
}
},
"security": [
{
"auth_http_bearer": [],
"auth_query_parameter": []
}
]
}
},
"/audio/{file}": {
"get": {
"tags": [
"Collection"
],
"summary": "Access a media file in the collection",
"operationId": "getAudio",
"parameters": [
{
"name": "file",
"in": "path",
"description": "Path to the desired file",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"audio/*": {
"schema": {
"format": "binary"
}
}
}
}
},
"security": [
{
"auth_http_bearer": [],
"auth_query_parameter": []
}
]
}
},
"/thumbnail/{file}": {
"get": {
"tags": [
"Collection"
],
"summary": "Generate an image thumbnail for a media file in the collection",
"operationId": "getServe",
"parameters": [
{
"name": "file",
"in": "path",
"description": "Path to the desired file",
"schema": {
"type": "string"
}
},
{
"name": "size",
"in": "query",
"description": "The maximum size of the thumbnail: tiny (40x40), small (400x400), large (1200x1200) or native",
"schema": {
"type": "string",
"enum": [
"tiny",
"small",
"large",
"native"
],
"default": "small"
}
},
{
"name": "pad",
"in": "query",
"description": "Indicates whether the thumbnail should be padded to a square aspect-ratio",
"schema": {
"type": "boolean",
"default": true
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"image/*": {
"schema": {
"format": "binary"
}
}
}
}
},
"security": [
{
"auth_http_bearer": [],
"auth_query_parameter": []
}
]
}
},
"/playlists": {
"get": {
"tags": [
"Playlists"
],
"summary": "Lists the playlists belonging to the current user",
"operationId": "getPlaylists",
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ListPlaylistsEntry"
}
}
}
}
}
},
"security": [
{
"auth_http_bearer": [],
"auth_query_parameter": []
}
]
}
},
"/playlist/{playlistName}": {
"get": {
"tags": [
"Playlists"
],
"summary": "Reads the content of a playlist",
"operationId": "getPlaylist",
"parameters": [
{
"name": "playlistName",
"in": "path",
"description": "Name of the playlist to read",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/APIVersion"
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Song"
}
}
}
}
}
},
"security": [
{
"auth_http_bearer": [],
"auth_query_parameter": []
}
]
},
"put": {
"tags": [
"Playlists"
],
"summary": "Saves a playlist",
"operationId": "putPlaylist",
"parameters": [
{
"name": "playlistName",
"in": "path",
"description": "Name of the playlist to save",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SavePlaylistInput"
}
}
}
},
"responses": {
"200": {
"description": "Successful operation"
}
},
"security": [
{
"auth_http_bearer": [],
"auth_query_parameter": []
}
]
},
"delete": {
"tags": [
"Playlists"
],
"summary": "Deletes a playlist",
"operationId": "deletePlaylist",
"parameters": [
{
"name": "playlistName",
"in": "path",
"description": "Name of the playlist to delete",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful operation"
}
},
"security": [
{
"auth_http_bearer": [],
"auth_query_parameter": []
}
]
}
}
},
"components": {
"schemas": {
"Version": {
"type": "object",
"properties": {
"major": {
"type": "integer",
"format": "int64",
"example": 3
},
"minor": {
"type": "integer",
"format": "int64",
"example": 0
}
}
},
"InitialSetup": {
"type": "object",
"properties": {
"has_any_users": {
"type": "boolean"
}
}
},
"Settings": {
"type": "object",
"properties": {
"album_art_pattern": {
"type": "string",
"example": "^Folder.(png|jpg|jpeg)$"
},
"reindex_every_n_seconds": {
"type": "integer",
"example": 3600
},
"ydns": {
"type": "object",
"properties": {
"host": {
"type": "string",
"example": "yourname.ydns.eu"
},
"username": {
"type": "string",
"example": "you@host.com"
},
"password": {
"type": "string",
"example": "hunter2"
}
}
}
}
},
"User": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"is_admin": {
"type": "boolean"
}
},
"required": [
"name",
"is_admin"
]
},
"NewUser": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"password": {
"type": "string"
},
"is_admin": {
"type": "boolean"
}
},
"required": [
"name",
"password",
"is_admin"
]
},
"UserUpdate": {
"type": "object",
"properties": {
"password": {
"type": "string"
},
"is_admin": {
"type": "boolean"
}
}
},
"MountDir": {
"type": "object",
"properties": {
"source": {
"type": "string",
"example": "/mnt/some_drive/music"
},
"name": {
"type": "string",
"example": "My Music"
}
},
"required": [
"source",
"name"
]
},
"Preferences": {
"type": "object",
"properties": {
"web_theme_base": {
"type": "string"
},
"web_theme_accent": {
"type": "string"
}
}
},
"Credentials": {
"type": "object",
"properties": {
"username": {
"type": "string"
},
"password": {
"type": "string"
}
}
},
"Authorization": {
"type": "object",
"properties": {
"username": {
"type": "string"
},
"token": {
"type": "string"
},
"is_admin": {
"type": "bool"
}
}
},
"CollectionFile": {
"oneOf": [
{
"$ref": "#/components/schemas/CollectionFileDirectory"
},
{
"$ref": "#/components/schemas/CollectionFileSong"
}
]
},
"CollectionFileDirectory": {
"type": "object",
"properties": {
"Directory": {
"$ref": "#/components/schemas/Directory"
}
}
},
"CollectionFileSong": {
"type": "object",
"properties": {
"Song": {
"$ref": "#/components/schemas/Song"
}
}
},
"Directory": {
"type": "object",
"properties": {
"path": {
"type": "string",
"example": "My Music/Metal/Stratovarius/Destiny",
"required": true
},
"artist": {
"type": "string",
"example": "Stratovarius"
},
"year": {
"type": "integer",
"example": 1998
},
"album": {
"type": "string",
"example": "Destiny"
},
"artwork": {
"type": "string",
"example": "My Music/Metal/Stratovarius/Destiny/Folder.png"
},
"date_added": {
"type": "integer",
"example": 1453179635,
"required": true
}
}
},
"Song": {
"type": "object",
"properties": {
"path": {
"type": "string",
"example": "My Music/Metal/Stratovarius/Destiny/Anthem of the World.mp3",
"required": true
},
"track_number": {
"type": "integer",
"example": 9
},
"disc_number": {
"type": "integer",
"example": 1
},
"title": {
"type": "string",
"example": "Anthem of the World"
},
"artists": {
"type": "array",
"items": {
"type": "string",
"example": "Stratovarius"
}
},
"album_artists": {
"type": "array",
"items": {
"type": "string",
"example": null
}
},
"year": {
"type": "integer",
"example": 1998
},
"album": {
"type": "string",
"example": "Destiny"
},
"artwork": {
"type": "string",
"example": "My Music/Metal/Stratovarius/Destiny/Folder.png"
},
"duration": {
"type": "integer",
"example": 571
},
"lyricists": {
"type": "array",
"items": {
"type": "string",
"example": "Timo Tolkki"
}
},
"composers": {
"type": "array",
"items": {
"type": "string",
"example": "Timo Tolkki"
}
},
"genres": {
"type": "array",
"items": {
"type": "string",
"example": "Metal"
}
},
"labels": {
"type": "array",
"items": {
"type": "string",
"example": "Noise Records"
}
}
}
},
"ListPlaylistsEntry": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "Friday Chill"
}
}
},
"SavePlaylistInput": {
"type": "object",
"properties": {
"tracks": {
"type": "array",
"items": {
"type": "string",
"example": "My Music/Metal/Stratovarius/Destiny/Anthem of the World.mp3"
}
}
}
}
},
"parameters": {
"APIVersion": {
"name": "Accept-Version",
"in": "header",
"description": "Major version of Polaris API this client understands. If omitted, server assumes version 7.",
"schema": {
"type": "integer"
}
}
},
"securitySchemes": {
"auth_http_bearer": {
"type": "http",
"scheme": "bearer",
"description": "An authentication token obtained in the output of the `auth` endpoint"
},
"admin_http_bearer": {
"type": "http",
"scheme": "bearer",
"description": "Identical to the auth_http_bearer scheme but only for users recognized as admin by the Polaris server"
},
"auth_query_parameter": {
"type": "apikey",
"in": "query",
"name": "auth_token",
"description": "An authentication token obtained in the output of the `auth` endpoint"
},
"admin_query_parameter": {
"type": "apikey",
"in": "query",
"name": "auth_token",
"description": "Identical to the auth_query_parameter scheme but only for users recognized as admin by the Polaris server"
}
},
"links": {},
"callbacks": {}
},
"security": []
}