koel/api-docs/collection.json

{"variables":[],"info":{"name":"","_postman_id":"682e0a2f-885e-4548-9afa-16b603709745","description":"","schema":"https:\/\/schema.getpostman.com\/json\/collection\/v2.0.0\/collection.json"},"item":[{"name":"1. Authentication","description":"","item":[{"name":"Log a user in","request":{"url":"http:\/\/localhost\/api\/me","method":"POST","body":{"mode":"formdata","formdata":[{"key":"email","value":"john@doe.com","type":"text","enabled":true},{"key":"password","value":"SoSecureMuchW0w","type":"text","enabled":true}]},"description":"Koel uses [JSON Web Tokens](https:\/\/jwt.io\/) (JWT) for authentication.\nAfter the user has been authenticated, a random \"token\" will be returned.\nThis token should then be saved in a local storage and used as an `Authorization: Bearer` header\nfor consecutive calls.\n\nNotice: The token is valid for a week, after that the user will need to log in again.","response":[]}},{"name":"Log the current user out","request":{"url":"http:\/\/localhost\/api\/me","method":"DELETE","body":{"mode":"formdata","formdata":[]},"description":"","response":[]}}]},{"name":"2. Application data","description":"","item":[{"name":"Get application data","request":{"url":"http:\/\/localhost\/api\/data","method":"GET","body":{"mode":"formdata","formdata":[]},"description":"The big fat call to retrieve a set of application data catered for the current user\n(songs, albums, artists, playlists, interactions, and if the user is an admin, settings as well).\nNaturally, this call should be made right after the user has been logged in, when you need to populate\nthe application's interface with useful information.","response":[]}}]},{"name":"3. Song interactions","description":"","item":[{"name":"Play a song","request":{"url":"http:\/\/localhost\/api\/{song}\/play\/{transcode?}\/{bitrate?}","method":"GET","body":{"mode":"formdata","formdata":[]},"description":"The GET request to play\/stream a song. By default Koel will serve the file as-is, unless it's a FLAC.\nIf the value of `transcode` is truthy, Koel will attempt to transcode the file into `bitRate`kbps using ffmpeg.","response":[]}},{"name":"Increase play count","request":{"url":"http:\/\/localhost\/api\/interaction\/play","method":"POST","body":{"mode":"formdata","formdata":[{"key":"song","value":"0146d01afb742b01f28ab8b556f9a75d","type":"text","enabled":true}]},"description":"Increase a song's play count as the currently authenticated user.\nThis request should be made whenever a song is played.\nAn \"interaction\" record including the song and current user's data will be returned.","response":[]}},{"name":"Like or unlike a song","request":{"url":"http:\/\/localhost\/api\/interaction\/like","method":"POST","body":{"mode":"formdata","formdata":[{"key":"song","value":"0146d01afb742b01f28ab8b556f9a75d","type":"text","enabled":true}]},"description":"An \"interaction\" record including the song and current user's data will be returned.","response":[]}},{"name":"Like multiple songs","request":{"url":"http:\/\/localhost\/api\/interaction\/batch\/like","method":"POST","body":{"mode":"formdata","formdata":[{"key":"songs","value":"[]","type":"text","enabled":true}]},"description":"Like several songs at once, useful for \"batch\" actions. An array of \"interaction\" records containing the song\nand user data will be returned.","response":[]}},{"name":"Unlike multiple songs","request":{"url":"http:\/\/localhost\/api\/interaction\/batch\/unlike","method":"POST","body":{"mode":"formdata","formdata":[{"key":"songs","value":"[]","type":"text","enabled":true}]},"description":"Unlike several songs at once, useful for \"batch\" actions. An array of \"interaction\" records containing the song\nand user data will be returned.","response":[]}},{"name":"Get recently played songs","request":{"url":"http:\/\/localhost\/api\/interaction\/recently-played\/{count?}","method":"GET","body":{"mode":"formdata","formdata":[]},"description":"Get a list of songs recently played by the current user.","response":[]}}]},{"name":"4. Playlist management","description":"","item":[{"name":"Get current user's playlists","request":{"url":"http:\/\/localhost\/api\/playlist","method":"GET","body":{"mode":"formdata","formdata":[]},"description":"","response":[]}},{"name":"Create a new playlist","request":{"url":"http:\/\/localhost\/api\/playlist","method":"POST","body":{"mode":"formdata","formdata":[{"key":"name","value":"Sleepy Songs","type":"text","enabled":true},{"key":"rules","value":"[]","type":"text","enabled":true}]},"description":"","response":[]}},{"name":"Rename a playlist","request":{"url":"http:\/\/localhost\/api\/playlist\/{playlist}","method":"PUT","body":{"mode":"formdata","formdata":[{"key":"name","value":"Catchy Songs","type":"text","enabled":true}]},"description":"","response":[]}},{"name":"Delete a playlist","request":{"url":"http:\/\/localhost\/api\/playlist\/{playlist}","method":"DELETE","body":{"mode":"formdata","formdata":[]},"description":"","response":[]}},{"name":"Replace a playlist's content","request":{"url":"http:\/\/localhost\/api\/playlist\/{playlist}\/sync","method":"PUT","body":{"mode":"formdata","formdata":[{"key":"songs","value":"[]","type":"text","enabled":true}]},"description":"Instead of adding or removing songs individually, a playlist's content is replaced entirely with an array of song IDs.","response":[]}},{"name":"Get a playlist's songs","request":{"url":"http:\/\/localhost\/api\/playlist\/{playlist}\/songs","method":"GET","body":{"mode":"formdata","formdata":[]},"description":"","response":[]}}]},{"name":"5. Media information","description":"","item":[{"name":"Update song information","request":{"url":"http:\/\/localhost\/api\/songs","method":"PUT","body":{"mode":"formdata","formdata":[{"key":"songs","value":"[]","type":"text","enabled":true},{"key":"data","value":"{}","type":"text","enabled":true}]},"description":"","response":[]}},{"name":"Get album's extra information","request":{"url":"http:\/\/localhost\/api\/album\/{album}\/info","method":"GET","body":{"mode":"formdata","formdata":[]},"description":"Get extra information about an album via Last.fm.","response":[]}},{"name":"Get artist's extra information","request":{"url":"http:\/\/localhost\/api\/artist\/{artist}\/info","method":"GET","body":{"mode":"formdata","formdata":[]},"description":"Get extra information about an artist via Last.fm.","response":[]}},{"name":"Get song's extra information","request":{"url":"http:\/\/localhost\/api\/song\/{song}\/info","method":"GET","body":{"mode":"formdata","formdata":[]},"description":"Get a song's extra information. The response of this request is a superset of both corresponding\n`album\/{album}\/info` and `artist\/{artist}\/info` requests, combined with the song's lyrics and related YouTube\nvideos, if applicable. This means you can (and should) cache this information somewhere ;)","response":[]}}]},{"name":"6. Download","description":"","item":[{"name":"Download one or several songs","request":{"url":"http:\/\/localhost\/api\/download\/songs","method":"GET","body":{"mode":"formdata","formdata":[]},"description":"","response":[]}},{"name":"Download a whole album","request":{"url":"http:\/\/localhost\/api\/download\/album\/{album}","method":"GET","body":{"mode":"formdata","formdata":[]},"description":"","response":[]}},{"name":"Download all songs by an artist","request":{"url":"http:\/\/localhost\/api\/download\/artist\/{artist}","method":"GET","body":{"mode":"formdata","formdata":[]},"description":"Don't see why one would need this, really.\nLet's pray to God the user doesn't trigger this on Elvis.","response":[]}},{"name":"Download a whole playlist","request":{"url":"http:\/\/localhost\/api\/download\/playlist\/{playlist}","method":"GET","body":{"mode":"formdata","formdata":[]},"description":"","response":[]}},{"name":"Download all songs favorite'd by the current user","request":{"url":"http:\/\/localhost\/api\/download\/favorites","method":"GET","body":{"mode":"formdata","formdata":[]},"description":"","response":[]}}]},{"name":"7. User management","description":"","item":[{"name":"Create a new user","request":{"url":"http:\/\/localhost\/api\/user","method":"POST","body":{"mode":"formdata","formdata":[{"key":"name","value":"John Doe","type":"text","enabled":true},{"key":"email","value":"john@doe.com","type":"text","enabled":true},{"key":"password","value":"SoSecureMuchW0w","type":"text","enabled":true}]},"description":"","response":[]}},{"name":"Update a user","request":{"url":"http:\/\/localhost\/api\/user\/{user}","method":"PUT","body":{"mode":"formdata","formdata":[{"key":"name","value":"Johny Doe","type":"text","enabled":true},{"key":"email","value":"johny@doe.com","type":"text","enabled":true},{"key":"password","value":"wJgmKkTITwHmdgUG","type":"text","enabled":true}]},"description":"","response":[]}},{"name":"Delete a user","request":{"url":"http:\/\/localhost\/api\/user\/{user}","method":"DELETE","body":{"mode":"formdata","formdata":[]},"description":"","response":[]}},{"name":"Get current user's profile","request":{"url":"http:\/\/localhost\/api\/me","method":"GET","body":{"mode":"formdata","formdata":[]},"description":"","response":[]}},{"name":"Update current user's profile","request":{"url":"http:\/\/localhost\/api\/me","method":"PUT","body":{"mode":"formdata","formdata":[{"key":"name","value":"Johny Doe","type":"text","enabled":true},{"key":"email","value":"johny@doe.com","type":"text","enabled":true},{"key":"password","value":"Lm4qQDyLb3NNddWI","type":"text","enabled":true}]},"description":"","response":[]}}]},{"name":"8. Settings","description":"","item":[{"name":"Save the application settings","request":{"url":"http:\/\/localhost\/api\/settings","method":"POST","body":{"mode":"formdata","formdata":[{"key":"media_path","value":"\/var\/www\/media\/","type":"text","enabled":true}]},"description":"Save the application settings. Right now there's only one setting to be saved (`media_path`).","response":[]}}]},{"name":"AWS integration\n\nThese routes are meant for Amazon Web Services (AWS) integration with Koel. For more information, visit\n[koel-aws](https:\/\/github.com\/koel\/koel-aws).","description":"","item":[{"name":"Store a song","request":{"url":"http:\/\/localhost\/api\/os\/s3\/song","method":"POST","body":{"mode":"formdata","formdata":[]},"description":"Create a new song or update an existing one with data sent from AWS.","response":[]}},{"name":"Remove a song","request":{"url":"http:\/\/localhost\/api\/os\/s3\/song","method":"DELETE","body":{"mode":"formdata","formdata":[]},"description":"Remove a song whose information matches with data sent from AWS.","response":[]}}]},{"name":"Last.fm integration","description":"","item":[{"name":"Scrobble a song","request":{"url":"http:\/\/localhost\/api\/{song}\/scrobble\/{timestamp}","method":"POST","body":{"mode":"formdata","formdata":[]},"description":"Create a [Last.fm scrobble entry](https:\/\/www.last.fm\/api\/scrobbling) for a song.","response":[]}},{"name":"Connect to Last.fm","request":{"url":"http:\/\/localhost\/api\/lastfm\/connect","method":"GET","body":{"mode":"formdata","formdata":[]},"description":"[Connect](https:\/\/www.last.fm\/api\/authentication) the current user to Last.fm.\nThis is actually NOT an API request. The application should instead redirect the current user to this route,\nwhich will send them to Last.fm for authentication. After authentication is successful, the user will be\nredirected back to `api\/lastfm\/callback?token=<Last.fm token>`.","response":[]}},{"name":"Set Last.fm session key","request":{"url":"http:\/\/localhost\/api\/lastfm\/session-key","method":"POST","body":{"mode":"formdata","formdata":[{"key":"key","value":"9mVYhfjKFsD9W160","type":"text","enabled":true}]},"description":"Set the Last.fm session key for the current user. This call should be made after the user is\n[connected to Last.fm](https:\/\/www.last.fm\/api\/authentication).","response":[]}}]},{"name":"YouTube integration","description":"","item":[{"name":"Search for YouTube videos","request":{"url":"http:\/\/localhost\/api\/youtube\/search\/song\/{song}","method":"GET","body":{"mode":"formdata","formdata":[{"key":"pageToken","value":"26tAbdCbQhXPqp73","type":"text","enabled":true}]},"description":"Search YouTube for videos related to a song (using its title and artist name).","response":[]}}]}]}