description:'If provided, will update the user''s password'
is_admin:
type:boolean
required:
- name
- email
- is_admin
delete:
summary:Delete a user
tags:
- user
responses:
'204':
description:NoContent
operationId:delete-user-userId
description:Delete a user
security:
- Bearer Token:[]
/api/me:
get:
summary:Get profile
tags:
- authentication
responses:
'200':
description:OK
content:
application/json:
schema:
$ref:'#/components/schemas/User'
operationId:get-me
security:
- Bearer Token:[]
description:Get the current user's profile
post:
summary:Log in
tags:
- authentication
responses:
'200':
description:OK
content:
application/json:
schema:
type:object
properties:
token:
type:string
required:
- token
operationId:post-me
description:'Log a user in. Upon a successful login, an API token will be returned. This token should be stored for further authenticated request (either as a Bearer token or as an `api-token` parameter).'
description:'If provided, will update the current user''s password'
required:
- name
- email
delete:
summary:Log out
tags:
- authentication
responses:
'204':
description:NoContent
operationId:delete-me
description:Log the current user out
security:
- Bearer Token:[]
parameters:[]
/api/data:
get:
summary:Get application data
tags:
- data
responses:
'200':
description:OK
content:
application/json:
schema:
type:object
properties:
albums:
type:array
items:
$ref:'#/components/schemas/Album'
allowDownload:
type:boolean
description:Whether the current installation of Koel allows downloading
artists:
type:array
items:
$ref:'#/components/schemas/Artist'
cdnUrl:
type:string
format:uri
description:'The CDN URL of the application, if configured'
currentUser:
$ref:'#/components/schemas/User'
currentVersion:
type:string
description:Version of the current installation of Koel
latestVersion:
type:string
description:The latest version of Koel
playlists:
type:array
items:
$ref:'#/components/schemas/Playlist'
recentlyPlayed:
type:array
description:An array containing the IDs of the most recently-played songs
items:
type:string
settings:
type:object
description:Settings for the current Koel installation. Only available if the current authenticated user is an admin.
properties:
media_path:
type:string
required:
- media_path
songs:
type:array
items:
$ref:'#/components/schemas/Song'
supportsTranscoding:
type:boolean
description:Whether the current installation of Koel supports transcoding media
useLastfm:
type:boolean
useYouTube:
type:boolean
useiTunes:
type:boolean
users:
description:Only available if the current authenticated user is an admin
type:array
items:
$ref:'#/components/schemas/User'
interactions:
type:array
items:
$ref:'#/components/schemas/InteractionExcerpt'
required:
- albums
- allowDownload
- artists
- cdnUrl
- currentUser
- currentVersion
- latestVersion
- playlists
- recentlyPlayed
- songs
- supportsTranscoding
- useLastfm
- useYouTube
- useiTunes
- interactions
operationId:get-data
description:'Retrieve a set of application data catered for the current authenticated user (songs, albums, artists, playlists, interactions, and if the user is an admin, settings as well). This call should typically be made right after the user is logged in, to populate the application''s interface with relevant information.'
security:
- Bearer Token:[]
parameters:[]
/api/interaction/play:
post:
summary:Increase play count
responses:
'200':
description:OK
content:
application/json:
schema:
$ref:'#/components/schemas/Interaction'
operationId:post-interaction-play
description:'Increase a song''s play count as the currently authenticated user. This request should be made whenever a song is played. '
security:
- Bearer Token:[]
requestBody:
content:
application/json:
schema:
type:object
properties:
song:
type:string
description:ID of the song
required:
- song
tags:
- interaction
parameters:[]
/api/interaction/like:
post:
summary:Toggle like/unlike a song
responses:
'200':
description:OK
content:
application/json:
schema:
$ref:'#/components/schemas/Interaction'
operationId:post-interaction-like
description:Toggle like ("favorite") or unlike ("unfavorite") a song. The "liked" status of the song will be reversed by this operation.
security:
- Bearer Token:[]
requestBody:
content:
application/json:
schema:
type:object
properties:
song:
type:string
description:ID of the song
required:
- song
tags:
- interaction
/api/interaction/batch/like:
post:
summary:Like multiple songs
tags:
- interaction
responses:
'200':
description:OK
content:
application/json:
schema:
type:array
items:
$ref:'#/components/schemas/Interaction'
operationId:post-interaction-batch-like
description:'Like several songs at once, useful for "batch" (e.g., drag-and-drop) actions'
security:
- Bearer Token:[]
requestBody:
content:
application/json:
schema:
type:object
properties:
songs:
type:array
description:An array of song IDs
items:
type:string
required:
- songs
parameters:[]
/api/interaction/batch/unlike:
post:
summary:Unlike multiple songs
tags:
- interaction
responses:
'204':
description:OK
operationId:post-interaction-batch-unlike
description:'Unlike several songs at once, useful for "batch" (e.g., drag-and-drop) actions'
security:
- Bearer Token:[]
requestBody:
content:
application/json:
schema:
type:object
properties:
songs:
type:array
description:An array of song IDs
items:
type:string
required:
- songs
'/api/interaction/recently-played/{count}':
parameters:
- schema:
type:integer
name:count
in:path
description:The maximum number of songs to be returned (optional)
get:
summary:Get recently played songs
tags:
- interaction
responses:
'200':
description:OK
content:
application/json:
schema:
type:array
description:An array of song IDs
items:
type:string
operationId:get-interaction-recently-played-count
description:Get a list of songs recently played by the current authenticated user
security:
- Bearer Token:[]
/api/playlist:
get:
summary:Get current user's playlists
tags:
- playlist
responses:
'200':
description:OK
content:
application/json:
schema:
type:array
items:
$ref:'#/components/schemas/Playlist'
operationId:get-playlist
description:Get all playlists owned by the current authenticated user
security:
- Bearer Token:[]
post:
summary:Create another playlist
tags:
- playlist
responses:
'200':
description:OK
content:
application/json:
schema:
$ref:'#/components/schemas/Playlist'
operationId:post-playlist
description:Create a new playlist that's owned by the current authenticated user
description:'Update a playlist (name and, if a smart playlist, its rules)'
security:
- Bearer Token:[]
requestBody:
content:
application/json:
schema:
type:object
properties:
name:
type:string
rules:
type:array
items:
$ref:'#/components/schemas/Playlist'
delete:
summary:''
operationId:delete-playlist-playlistId
responses:
'200':
description:OK
description:Delete a playlist
security:
- Bearer Token:[]
get:
summary:Get playlist's songs
operationId:get-playlist-playlistId
responses:
'200':
description:OK
content:
application/json:
schema:
type:array
description:An array of song IDs
items:
type:string
description:Get a playlist's songs
security:
- Bearer Token:[]
'/api/playlist/{playlistId}/sync':
parameters:
- schema:
type:integer
name:playlistId
in:path
required:true
description:ID of the playlist
put:
summary:''
operationId:put-playlist-playlistId-sync
responses:
'200':
description:OK
description:'Populate playlist''s content. Instead of adding or removing songs individually, a playlist''s content is replaced entirely with an array of song IDs.'
requestBody:
content:
application/json:
schema:
type:object
properties:
songs:
type:array
description:An array of song IDs
items:
type:string
required:
- songs
/api/songs:
put:
summary:Update song(s) information
tags:
- media information
responses:
'200':
description:OK
content:
application/json:
schema:
type:object
properties:
artists:
type:array
items:
$ref:'#/components/schemas/Artist'
albums:
type:array
items:
$ref:'#/components/schemas/Album'
songs:
type:array
items:
$ref:'#/components/schemas/Song'
required:
- artists
- albums
- songs
operationId:put-songs
description:Update the information of a song or multiple songs
security:
- Bearer Token:[]
requestBody:
content:
application/json:
schema:
type:object
properties:
songs:
type:array
items:
type:string
data:
type:object
properties:
title:
type:string
artistName:
type:string
albumName:
type:string
lyrics:
type:string
required:
- songs
- data
'/api/album/{albumId}/info':
parameters:
- schema:
type:integer
name:albumId
in:path
required:true
description:ID of the album
get:
summary:Get album's extra information
tags:
- media information
responses:
'200':
description:OK
content:
application/json:
schema:
$ref:'#/components/schemas/AlbumExtraInformation'
operationId:get-album-albumId-info
description:'Get extra information (image, description etc.) about an album. Currently this information is only available if Last.fm integration is enabled. If it''s not the case, `null` will be returned.'
description:'Get extra information (image, biography etc.) about an artist. Currently this information is only available if Last.fm integration is enabled. If it''s not the case, `null` will be returned.'
description:'Get a song''s extra information. The response of this request is a superset of both corresponding `album/{albumId}/info` and `artist/{artistId}/info` responses, combined with the song''s lyrics and related YouTube videos, if applicable. '
security:
- Bearer Token:[]
'/api/album/{albumId}/cover':
parameters:
- schema:
type:integer
name:albumId
in:path
required:true
description:ID of the album
put:
summary:Upload album's cover
tags:
- media information
responses:
'200':
description:OK
content:
application/json:
schema:
type:object
properties:
coverUrl:
type:string
format:uri
required:
- coverUrl
operationId:put-album-albumId-cover
description:Upload an image as an album's cover
security:
- Bearer Token:[]
requestBody:
content:
application/json:
schema:
type:object
properties:
cover:
description:'The cover image''s content, in [Data URI format](https://en.wikipedia.org/wiki/Data_URI_scheme)'
type:string
required:
- cover
'/api/artist/{artistId}/image':
parameters:
- schema:
type:integer
name:artistId
in:path
required:true
description:ID of the artist
put:
summary:Upload artist's image
tags:
- media information
responses:
'200':
description:OK
content:
application/json:
schema:
type:object
properties:
imageUrl:
type:string
format:uri
required:
- imageUrl
operationId:put-artist-artistId-image
description:Upload an artist's image
security:
- Bearer Token:[]
requestBody:
content:
application/json:
schema:
type:object
properties:
image:
type:string
description:'The image''s content, in [Data URI format](https://en.wikipedia.org/wiki/Data_URI_scheme)'
required:
- image
'/api/album/{album}/thumbnail':
parameters:
- schema:
type:integer
name:album
in:path
required:true
description:ID of the album
get:
summary:Get album's thumbnail
tags:
- media information
responses:
'200':
description:OK
content:
application/json:
schema:
type:
- object
- 'null'
properties:
thumbnailUrl:
type:string
format:uri
required:
- thumbnailUrl
operationId:get-album-album-thumbnail
description:Get an album's thumbnail (a 48px-wide blurry version of the album's cover). Returns the full URL to the thumbnail or NULL if the album has no cover.
description:Save the application settings. Right now there's only one setting to be saved (`media_path`). The current authenticated user must be an admin.
security:
- Bearer Token:[]
requestBody:
content:
application/json:
schema:
type:object
properties:
media_path:
type:string
description:Absolute path to the media folder
required:
- media_path
/api/os/s3/song:
post:
summary:Save a song from S3
tags:
- S3 integration
responses:
'200':
description:OK
content:
application/json:
schema:
$ref:'#/components/schemas/Song'
operationId:post-os-s3-song
description:Create a new song or update an existing one with data sent from AWS
description:Upload a song. The current authenticated user must be an admin.
security:
- Bearer Token:[]
requestBody:
content:
multipart/form-data:
schema:
type:object
properties:
file:
type:string
format:binary
required:
- file
'/api/{songId}/scrobble':
parameters:
- schema:
type:string
name:songId
in:path
required:true
description:ID of the song
post:
summary:Scrobble a song
tags:
- last.fm
responses:
'204':
description:NoContent
operationId:post-api-songId-scrobble
description:'Create a [Last.fm scrobble entry](https://www.last.fm/api/scrobbling) for a song. Only functional if Last.fm integration has been configured and the current authenticated user has connected to Last.fm.'
security:
- Bearer Token:[]
requestBody:
content:
application/json:
schema:
type:object
properties:
timestamp:
type:integer
/api/lastfm/session-key:
post:
summary:Set Last.fm session key
tags:
- last.fm
responses:
'204':
description:NoContent
operationId:post-api-lastfm-session-key
description:'Set the Last.fm session key for the current authenticated user. This call should be made after the user is [connected to Last.fm](https://www.last.fm/api/authentication).'
description:'[Connect](https://www.last.fm/api/authentication) the current user to Last.fm. This is actually NOT an API request. The application should instead redirect the current user to this route, which will send them to Last.fm for authentication. After authentication is successful, the user will be redirected back to `/lastfm/callback?token=<Last.fm token>`.'
description:Whether to transcode the song (optional)
- schema:
type:number
name:bitrate
in:path
description:Bit rate to transcode to (optional)
get:
summary:Play a song
tags:
- playback
responses:{}
operationId:get-play-songId-transcode-bitrate
description:'The GET request to play/stream a song. This is NOT an XmlHttpRequest By default Koel will serve the file as-is, unless it''s a FLAC file. If the value of `transcode` is truthy, Koel will attempt to transcode the file into `bitRate` kbps using ffmpeg.'
description:Download a song or several songs. This is NOT an XmlHttpRequest. The response will be a download response of either the media file or a zip file containing multiple media files.
description:Download a whole album. This is NOT an XmlHttpRequest. The response will be a download response of either one media file or a zip file containing multiple media files.
description:Download a whole artist's biography. This is NOT an XmlHttpRequest. The response will be a download response of either one media file or a zip file containing multiple media files.
description:Download a whole playlist. This is NOT an XmlHttpRequest. The response will be a download response of either one media file or a zip file containing multiple media files.
summary:Innuendo is a 1991 album by English rock band Queen...
full:Innuendo is a 1991 album by English rock band Queen. It is the band's fourteenth studio album and the last to be composed entirely of new material. It is also their final studio album to be released while lead singer Freddie Mercury was still alive.
summary:Queen were an English rock band originally consisting of four members...
full: 'Queen were an English rock band originally consisting of four members:vocalist Freddie Mercury, guitarist Brian May, bass guitarist John Deacon, and drummer Roger Taylor.'
YouTubeSearchResult:
title:YouTubeSearchResult
type:object
description:A search result object returned by YouTube
title:Queen - The Show Must Go On (Official Video)
description:'Subscribe to the Official Queen Channel Here http://bit.ly/Subscribe2Queen Taken from Innuendo, 1991. Queen - The Show Must Go On (promo video, 1991) ...'
