Get user profile information
Get user's top tracks. Optional query param 'term' (short_term, medium_term, long_term)
Get user's top artists. Optional query param 'term' (short_term, medium_term, long_term)
Get user's top albums (derived from top tracks). Optional query param 'term' (short_term, medium_term, long_term)
Get all albums
Get single album
Get all tracks
Get all playlists for the authenticated user. Query params: - limit: number (optional) - Maximum number of playlists to return. If not specified, returns all playlists. Returns: Object with userItems (user's own playlists) and likedItems (liked playlists) arrays.
Get all liked playlists
Create a new playlist
Get single playlist
Add tracks to a playlist
Remove tracks from a playlist
Search for tracks
Get top artists for genres
Get artist albums
Get artist related artists
Get artist top tracks
Get artist
Get audio analysis
Get audio features
Get audio features batch
Get recommendations
Get available genre seeds
Get track by id
Get user's saved tracks
Save tracks to user's library
Remove tracks from user's library
Check if tracks are saved to user's library
Check if albums are saved to user's library
Save albums to user's library
Remove albums from user's library
Get album tracks
Get album
Discover tracks based on user's top genres with caching and filtering. Query params: - term: short_term|medium_term|long_term (default: medium_term) - Time range for top artists - genres: number (default: 20) - Number of top genres to use - size: number (default: 50) - Number of tracks to return - swipeCount: number (default: 0) - Pagination offset - danceabilityLevel: low|medium|high (optional) - Filter genres by danceability level - energyLevel: low|medium|high (optional) - Filter genres by energy level - remix: true|false (default: true) - Include tracks with "remix" in title - acoustic: true|false (default: true) - Include tracks with "acoustic" in title - radio: true|false (default: true) - Include tracks with "radio" in title - mixes: true|false (default: true) - Include tracks with "mix" in title - instrumental: true|false (default: true) - Include tracks with "instrumental" in title Returns: Array of normalized track objects with preview_url, track_image, artist_image, etc. Uses genre-based caching (30 days TTL) and deterministic monthly ordering.
Get user's liked songs collection. Returns: Array of liked song objects for the authenticated user. - Limit: 100 songs (most recent first, ordered by created_at descending) - Each object contains: track_id, track_image, track_title, track_artist, artist_image, preview_url, playlist_id - Note: id, app_user_id, and created_at are excluded from the response Status codes: - 200: Success - 400: Invalid user ID - 401: User ID not found - 500: Server error
Save a track to user's liked songs collection. Request body: - track_id: string (required) - Spotify track ID - track_image: string (optional) - Track cover image URL - track_title: string (optional) - Track title - track_artist: string (optional) - Track artist name(s) - artist_image: string (optional) - Artist image URL - preview_url: string (optional) - Track preview URL - playlist_id: string (optional) - Spotify playlist ID. If provided, the track will be added to this playlist and stored in the database. This endpoint will: 1. Save the track to liked_songs table 2. If playlist_id is provided and spotifyToken is available, add the track to the specified Spotify playlist Returns: Success message. Status codes: - 201: Track liked successfully - 200: Track already liked (returns existing record) - 409: Unique constraint violation (track already exists) - 400: Invalid request (missing track_id or invalid user ID) - 401: User ID not found - 500: Server error Note: Each user can only like a track once (unique constraint on app_user_id + track_id). The playlist_id is stored in the database and will be used automatically when removing the track. If playlist addition fails, the track will still be saved in the database.
Remove a track from user's liked songs collection. Request body: - track_id: string (required) - Spotify track ID This endpoint will: 1. Find the track in liked_songs table and retrieve the stored playlist_id 2. Remove the track from liked_songs table 3. If playlist_id exists in the database record and spotifyToken is available, remove the track from that Spotify playlist Status codes: - 200: Track removed successfully - 404: Track not found in liked songs - 400: Invalid request (missing track_id or invalid user ID) - 401: User ID not found - 500: Server error Note: The playlist_id is automatically retrieved from the database record. If playlist removal fails, the track will still be removed from the database.
Get user's disliked songs collection. Returns: Array of disliked song objects for the authenticated user. - Limit: 100 songs (most recent first, ordered by created_at descending) - Each object contains: track_id, track_image, track_title, track_artist, artist_image, preview_url, playlist_id - Note: id, app_user_id, and created_at are excluded from the response Status codes: - 200: Success - 400: Invalid user ID - 401: User ID not found - 500: Server error
Save a track to user's disliked songs collection. Request body: - track_id: string (required) - Spotify track ID - track_image: string (optional) - Track cover image URL - track_title: string (optional) - Track title - track_artist: string (optional) - Track artist name(s) - artist_image: string (optional) - Artist image URL - preview_url: string (optional) - Track preview URL - playlist_id: string (optional) - Spotify playlist ID. If provided, this will be stored in the database for later use. Returns: Success message. Status codes: - 201: Track disliked successfully - 200: Track already disliked (returns existing record) - 409: Unique constraint violation (track already exists) - 400: Invalid request (missing track_id or invalid user ID) - 401: User ID not found - 500: Server error Note: Each user can only dislike a track once (unique constraint on app_user_id + track_id). The playlist_id is stored in the database for reference.
Remove a track from user's disliked songs collection. Request body: - track_id: string (required) - Spotify track ID This endpoint will: 1. Remove the track from disliked_songs table Status codes: - 200: Track removed successfully - 404: Track not found in disliked songs - 400: Invalid request (missing track_id or invalid user ID) - 401: User ID not found - 500: Server error
Move a track from liked songs to disliked songs. Request body: - track_id: string (required) - Spotify track ID - playlist_id: string (optional) - Spotify playlist ID. If provided, only the track from this specific playlist will be moved. This endpoint will: 1. Find the track in liked_songs (optionally filtered by playlist_id if provided) 2. Retrieve the playlist_id from the liked_songs record 3. If playlist_id exists and spotifyToken is available, remove the track from that Spotify playlist 4. Remove the track from liked_songs table 5. Add the track to disliked_songs table (preserving all track metadata including playlist_id) Status codes: - 200: Track moved successfully - 404: Track not found in liked songs - 400: Invalid request (missing track_id or invalid user ID) - 401: User ID not found - 500: Server error Note: If the track is already in disliked_songs, it will only be removed from liked_songs (and from playlist if applicable). If playlist_id is provided in the request, only that specific playlist's track will be moved. Uses database transaction to ensure atomicity. If playlist removal fails, the track will still be moved in the database.
Move a track from disliked songs to liked songs. Request body: - track_id: string (required) - Spotify track ID - playlist_id: string (optional) - Spotify playlist ID. If provided, only the track from this specific playlist will be moved. This endpoint will: 1. Find the track in disliked_songs (optionally filtered by playlist_id if provided) 2. Retrieve the playlist_id from the disliked_songs record 3. If playlist_id exists and spotifyToken is available, add the track to that Spotify playlist 4. Remove the track from disliked_songs table 5. Add the track to liked_songs table (preserving all track metadata including playlist_id) Status codes: - 200: Track moved successfully - 404: Track not found in disliked songs - 400: Invalid request (missing track_id or invalid user ID) - 401: User ID not found - 500: Server error Note: If the track is already in liked_songs, it will only be removed from disliked_songs (and added to playlist if applicable). If playlist_id is provided in the request, only that specific playlist's track will be moved. Uses database transaction to ensure atomicity. If playlist addition fails, the track will still be moved in the database.
Revert the user's last action (like or dislike). This endpoint automatically finds the most recent track action (like or dislike) and reverts it: - If the last action was a like, it removes the track from liked_songs (and from the playlist if playlist_id is stored in the database) - If the last action was a dislike, it removes the track from disliked_songs No request body required. The endpoint automatically: 1. Finds the most recent liked and disliked songs 2. Compares their timestamps to determine the last action 3. Retrieves playlist_id from the database record (if it was a liked song) 4. Removes the track from the database and optionally from Spotify playlist Returns: - message: Success message - trackId: The track ID that was reverted - type: 'liked' or 'disliked' - indicates which action was reverted Status codes: - 200: Action reverted successfully - 404: No recent action found to revert - 400: Invalid user ID - 401: User ID not found - 500: Server error Note: Compares the most recent liked and disliked songs by created_at timestamp to determine which action was last. If the reverted action was a like and playlist_id exists in the database, the track will also be removed from that Spotify playlist.