feat(api)!: sync specification (#460)

dargmuesli · Sep 7, 2026 · Feb 11, 2026 · Feb 11, 2026 · Feb 11, 2026 · Feb 11, 2026
commit e3c023331757604619cfa57ee3c7a0c90e5abdef
diff --git a/README.md b/README.md
@@ -222,132 +222,135 @@ access token only once, after which it becomes invalid.
 
 
 ## Examples
+
+> **Deprecated** examples are marked with ⚠️ and will be removed in v11.0. See the `@deprecated` Javadoc tag on the
+> corresponding request class for the recommended alternative.
+
 - **Albums**
   - [Get an Album](examples/data/albums/GetAlbumExample.java)
   - [Get an Album's Tracks](examples/data/albums/GetAlbumsTracksExample.java)
-  - [Get several Albums](examples/data/albums/GetSeveralAlbumsExample.java)
+  - [Check User's Saved Albums](examples/data/albums/CheckUsersSavedAlbumsExample.java)
+  - [Get Current User's Saved Albums](examples/data/albums/GetCurrentUsersSavedAlbumsExample.java)
 
 
 - **Artists**
   - [Get an Artist](examples/data/artists/GetArtistExample.java)
   - [Get an Artist's Albums](examples/data/artists/GetArtistsAlbumsExample.java)
-  - [Get an Artist's Top Tracks](examples/data/artists/GetArtistsTopTracksExample.java)
   - [Get an Artist's Related Artists](examples/data/artists/GetArtistsRelatedArtistsExample.java)
-  - [Get Several Artists](examples/data/artists/GetSeveralArtistsExample.java)
+  - ⚠️ [Get an Artist's Top Tracks](examples/data/artists/): deprecated; use search instead
+
+
+- **Audiobooks**
+  - [Get an Audiobook](examples/data/audiobooks/GetAudiobookExample.java)
+  - [Get an Audiobook's Chapters](examples/data/audiobooks/GetAudiobookChaptersExample.java)
+  - ⚠️ [Get Several Audiobooks](examples/data/audiobooks/GetSeveralAudiobooksExample.java)
+  - ⚠️ [Get User's Saved Audiobooks](examples/data/audiobooks/GetUsersSavedAudiobooksExample.java)
+  - ⚠️ [Check User's Saved Audiobooks](examples/data/audiobooks/CheckUsersSavedAudiobooksExample.java)
+  - ⚠️ [Save Audiobooks for Current User](examples/data/audiobooks/SaveAudiobooksForCurrentUserExample.java)
+  - ⚠️ [Remove Audiobooks for Current User](examples/data/audiobooks/RemoveAudiobooksForCurrentUserExample.java)
+
+
+- **Browsing & Discovery**
+  - [Get Available Genre Seeds](examples/data/genres/GetAvailableGenreSeedsExample.java)
+  - ⚠️ [Get Categories](examples/data/categories/GetSeveralBrowseCategoriesExample.java)
+  - ⚠️ [Get a Category](examples/data/categories/GetSingleBrowseCategoryExample.java)
+  - ⚠️ [Get a Category's Playlists](examples/data/playlists/GetCategoryPlaylistsExample.java)
+  - ⚠️ [Get Featured Playlists](examples/data/playlists/GetFeaturedPlaylistsExample.java)
+  - ⚠️ [Get Available Markets](examples/data/markets/GetAvailableMarketsExample.java)
 
 
-- **Browse**
-  - Miscellaneous
-    - [Get Available Genre Seeds](examples/data/browse/miscellaneous/GetAvailableGenreSeedsExample.java)
-  - [Get a Category](examples/data/browse/GetCategoryExample.java)
-  - [Get a Category's Playlists](examples/data/browse/GetCategorysPlaylistsExample.java)
-  - [Get a List of Categories](examples/data/browse/GetListOfCategoriesExample.java)
-  - [Get a List of Featured Playlists](examples/data/browse/GetListOfFeaturedPlaylistsExample.java)
-  - [Get a List of New Releases](examples/data/browse/GetListOfNewReleasesExample.java)
-  - [Get Recommendations](examples/data/browse/GetRecommendationsExample.java)
+- **Chapters**
+  - [Get a Chapter](examples/data/chapters/GetChapterExample.java)
+  - ⚠️ [Get Several Chapters](examples/data/chapters/GetSeveralChaptersExample.java)
 
 
 - **Episodes**
   - [Get an Episode](examples/data/episodes/GetEpisodeExample.java)
-  - [Get several Episodes](examples/data/episodes/GetSeveralEpisodesExample.java)
-
-
-- **Follow**
-  - [Check if Current User Follows Artists or Users](examples/data/follow/CheckCurrentUserFollowsArtistsOrUsersExample.java)
-  - [Check if Users Follow a Playlist](examples/data/follow/CheckUsersFollowPlaylistExample.java)
-  - [Follow Artists or Users](examples/data/follow/FollowArtistsOrUsersExample.java)
-  - [Follow a Playlist](examples/data/follow/FollowPlaylistExample.java)
-  - [Get User's Followed Artists](examples/data/follow/GetUsersFollowedArtistsExample.java)
-  - [Unfollow Artists or Users](examples/data/follow/UnfollowArtistsOrUsersExample.java)
-  - [Unfollow a Playlist](examples/data/follow/UnfollowPlaylistExample.java)
-
-
-- **Library**
-  - [Check User's Saved Albums](examples/data/library/CheckUsersSavedAlbumsExample.java)
-  - [Check User's Saved Episodes](examples/data/library/CheckUsersSavedEpisodesExample.java)
-  - [Check User's Saved Shows](examples/data/library/CheckUsersSavedShowsExample.java)
-  - [Check User's Saved Tracks](examples/data/library/CheckUsersSavedTracksExample.java)
-  - [Get Current User's Saved Albums](examples/data/library/GetCurrentUsersSavedAlbumsExample.java)
-  - [Get User's Saved Episodes](examples/data/library/GetUsersSavedEpisodesExample.java)
-  - [Get User's Saved Shows](examples/data/library/GetUsersSavedShowsExample.java)
-  - [Get User's Saved Tracks](examples/data/library/GetUsersSavedTracksExample.java)
-  - [Remove Albums for Current User](examples/data/library/RemoveAlbumsForCurrentUserExample.java)
-  - [Remove User's Saved Episodes](examples/data/library/RemoveUsersSavedEpisodesExample.java)
-  - [Remove User's Saved Shows](examples/data/library/RemoveUsersSavedShowsExample.java)
-  - [Remove User's Saved Tracks](examples/data/library/RemoveUsersSavedTracksExample.java)
-  - [Save Albums for Current User](examples/data/library/SaveAlbumsForCurrentUserExample.java)
-  - [Save Episodes for Current User](examples/data/library/SaveEpisodesForCurrentUserExample.java)
-  - [Save Shows for Current User](examples/data/library/SaveShowsForCurrentUserExample.java)
-  - [Save Tracks for User](examples/data/library/SaveTracksForUserExample.java)
+  - [Check User's Saved Episodes](examples/data/episodes/CheckUsersSavedEpisodesExample.java)
+  - [Get User's Saved Episodes](examples/data/episodes/GetUsersSavedEpisodesExample.java)
+
+
+- **Library (Unified Save/Remove/Check API)**
+  - [Save Items to Library](examples/data/library/SaveToLibraryExample.java)
+  - [Remove Items from Library](examples/data/library/RemoveFromLibraryExample.java)
 
 
 - **Personalization**
+  - [Get a User's Top Artists and Tracks](examples/data/users/GetUsersTopArtistsAndTracksExample.java)
   - Simplified
-    - [Get a User's Top Artists](examples/data/personalization/simplified/GetUsersTopArtistsExample.java)
-    - [Get a User's Top Tracks](examples/data/personalization/simplified/GetUsersTopTracksExample.java)
-  - [Get a User's Top Artists and Tracks](examples/data/personalization/GetUsersTopArtistsAndTracksExample.java)
+    - [Get a User's Top Artists](examples/data/users/simplified/GetUsersTopArtistsExample.java)
+    - [Get a User's Top Tracks](examples/data/users/simplified/GetUsersTopTracksExample.java)
 
 
 - **Player**
-  - [Add Item to User's Playback Queue](examples/data/player/AddItemToUsersPlaybackQueueExample.java)
-  - [Get a User's Available Devices](examples/data/player/GetUsersAvailableDevicesExample.java)
-  - [Get Information About The User's Current Playback](examples/data/player/GetInformationAboutUsersCurrentPlaybackExample.java)
-  - [Get Current User's Recently Played Tracks](examples/data/player/GetCurrentUsersRecentlyPlayedTracksExample.java)
-  - [Get the User's Currently Playing Track](examples/data/player/GetUsersCurrentlyPlayingTrackExample.java)
-  - [Pause a User's Playback](examples/data/player/PauseUsersPlaybackExample.java)
-  - [Seek To Position In Currently Playing Track](examples/data/player/SeekToPositionInCurrentlyPlayingTrackExample.java)
-  - [Set Repeat Mode On User's Playback](examples/data/player/SetRepeatModeOnUsersPlaybackExample.java)
-  - [Set Volume For User's Playback](examples/data/player/SetVolumeForUsersPlaybackExample.java)
-  - [Skip User's Playback To Next Track](examples/data/player/SkipUsersPlaybackToNextTrackExample.java)
-  - [Skip User's Playback To Previous Track](examples/data/player/SkipUsersPlaybackToPreviousTrackExample.java)
-  - [Start/Resume a User's Playback](examples/data/player/StartResumeUsersPlaybackExample.java)
-  - [Toggle Shuffle For User's Playback](examples/data/player/ToggleShuffleForUsersPlaybackExample.java)
-  - [Transfer a User's Playback](examples/data/player/TransferUsersPlaybackExample.java)
+  - [Get Available Devices](examples/data/player/GetUsersAvailableDevicesExample.java)
+  - [Get Current Playback State](examples/data/player/GetInformationAboutUsersCurrentPlaybackExample.java)
+  - [Get Currently Playing Track](examples/data/player/GetUsersCurrentlyPlayingTrackExample.java)
+  - [Get Recently Played Tracks](examples/data/player/GetCurrentUsersRecentlyPlayedTracksExample.java)
+  - [Get User's Queue](examples/data/player/GetTheUsersQueueExample.java)
+  - [Start/Resume Playback](examples/data/player/StartResumeUsersPlaybackExample.java)
+  - [Pause Playback](examples/data/player/PauseUsersPlaybackExample.java)
+  - [Skip to Next Track](examples/data/player/SkipUsersPlaybackToNextTrackExample.java)
+  - [Skip to Previous Track](examples/data/player/SkipUsersPlaybackToPreviousTrackExample.java)
+  - [Seek to Position](examples/data/player/SeekToPositionInCurrentlyPlayingTrackExample.java)
+  - [Set Repeat Mode](examples/data/player/SetRepeatModeOnUsersPlaybackExample.java)
+  - [Toggle Shuffle](examples/data/player/ToggleShuffleForUsersPlaybackExample.java)
+  - [Set Volume](examples/data/player/SetVolumeForUsersPlaybackExample.java)
+  - [Transfer Playback](examples/data/player/TransferUsersPlaybackExample.java)
+  - [Add Item to Queue](examples/data/player/AddItemToUsersPlaybackQueueExample.java)
 
 
 - **Playlists**
-  - [Add Items to a Playlist](examples/data/playlists/AddItemsToPlaylistExample.java)
-  - [Change a Playlist's Details](examples/data/playlists/ChangePlaylistsDetailsExample.java)
-  - [Create a Playlist](examples/data/playlists/CreatePlaylistExample.java)
-  - [Get a List of Current User's Playlists](examples/data/playlists/GetListOfCurrentUsersPlaylistsExample.java)
-  - [Get a List of a User's Playlists](examples/data/playlists/GetListOfUsersPlaylistsExample.java)
   - [Get a Playlist](examples/data/playlists/GetPlaylistExample.java)
-  - [Get a Playlist Cover Image](examples/data/playlists/GetPlaylistCoverImageExample.java)
+  - [Get Current User's Playlists](examples/data/playlists/GetCurrentUsersPlaylistsExample.java)
   - [Get a Playlist's Items](examples/data/playlists/GetPlaylistsItemsExample.java)
+  - [Get a Playlist Cover Image](examples/data/playlists/GetPlaylistCoverImageExample.java)
+  - [Add Items to a Playlist](examples/data/playlists/AddItemsToPlaylistExample.java)
   - [Remove Items from a Playlist](examples/data/playlists/RemoveItemsFromPlaylistExample.java)
-  - [Reorder a Playlist's Items](examples/data/playlists/ReorderPlaylistsItemsExample.java)
-  - [Replace a Playlist's Items](examples/data/playlists/ReplacePlaylistsItemsExample.java)
-  - [Upload a Custom Playlist Cover Image](examples/data/playlists/UploadCustomPlaylistCoverImageExample.java)
+  - [Update Playlist Details](examples/data/playlists/ChangePlaylistsDetailsExample.java)
+  - [Reorder Playlist Items](examples/data/playlists/UpdatePlaylistsItemsReorderExample.java)
+  - [Replace Playlist Items](examples/data/playlists/UpdatePlaylistsItemsReplaceExample.java)
+  - [Upload Playlist Cover Image](examples/data/playlists/UploadCustomPlaylistCoverImageExample.java)
+  - ⚠️ [Add Items (Deprecated Format)](examples/data/playlists/AddItemsToPlaylistDeprecatedExample.java)
 
 
 - **Search**
-  - Simplified
+  - [Search for Item](examples/data/search/SearchItemExample.java)
+  - Simplified (Direct Type Search)
     - [Search Albums](examples/data/search/simplified/SearchAlbumsExample.java)
     - [Search Artists](examples/data/search/simplified/SearchArtistsExample.java)
+    - [Search Tracks](examples/data/search/simplified/SearchTracksExample.java)
+    - [Search Shows](examples/data/search/simplified/SearchShowsExample.java)
     - [Search Episodes](examples/data/search/simplified/SearchEpisodesExample.java)
     - [Search Playlists](examples/data/search/simplified/SearchPlaylistsExample.java)
-    - [Search Shows](examples/data/search/simplified/SearchShowsExample.java)
-    - [Search Tracks](examples/data/search/simplified/SearchTracksExample.java)
-  - [Search Item](examples/data/search/SearchItemExample.java)
 
 
 - **Shows**
   - [Get a Show](examples/data/shows/GetShowExample.java)
-  - [Get several Show](examples/data/shows/GetSeveralShowsExample.java)
   - [Get a Show's Episodes](examples/data/shows/GetShowsEpisodesExample.java)
+  - [Check User's Saved Shows](examples/data/shows/CheckUsersSavedShowsExample.java)
+  - [Get User's Saved Shows](examples/data/shows/GetUsersSavedShowsExample.java)
 
 
 - **Tracks**
-  - [Get Audio Analysis for a Track](examples/data/tracks/GetAudioAnalysisForTrackExample.java)
+  - [Get a Track](examples/data/tracks/GetTrackExample.java)
+  - [Check User's Saved Tracks](examples/data/tracks/CheckUsersSavedTracksExample.java)
+  - [Get User's Saved Tracks](examples/data/tracks/GetUsersSavedTracksExample.java)
   - [Get Audio Features for a Track](examples/data/tracks/GetAudioFeaturesForTrackExample.java)
   - [Get Audio Features for Several Tracks](examples/data/tracks/GetAudioFeaturesForSeveralTracksExample.java)
-  - [Get Several Tracks](examples/data/tracks/GetSeveralTracksExample.java)
-  - [Get a Track](examples/data/tracks/GetTrackExample.java)
-
-
-- **User's Profile**
-  - [Get Current User's Profile](examples/data/users_profile/GetCurrentUsersProfileExample.java)
-  - [Get a User's Profile](examples/data/users_profile/GetUsersProfileExample.java)
+  - [Get Audio Analysis for a Track](examples/data/tracks/GetAudioAnalysisForTrackExample.java)
+  - [Get Recommendations](examples/data/tracks/GetRecommendationsExample.java)
+
+
+- **User's Profile & Following**
+  - [Get Current User's Profile](examples/data/users/GetCurrentUsersProfileExample.java)
+  - ⚠️ [Get User's Followed Artists](examples/data/users/GetUsersFollowedArtistsExample.java)
+  - ⚠️ [Follow Artists or Users](examples/data/users/FollowArtistsOrUsersExample.java)
+  - ⚠️ [Unfollow Artists or Users](examples/data/users/UnfollowArtistsOrUsersExample.java)
+  - ⚠️ [Check if User Follows Artists or Users](examples/data/users/CheckCurrentUserFollowsArtistsOrUsersExample.java)
+  - ⚠️ [Follow a Playlist](examples/data/users/FollowPlaylistExample.java)
+  - ⚠️ [Unfollow a Playlist](examples/data/users/UnfollowPlaylistExample.java)
+  - ⚠️ [Check if Users Follow a Playlist](examples/data/users/CheckUsersFollowPlaylistExample.java)
 
 ## Contributions
 See [CONTRIBUTING.md](CONTRIBUTING.md).

diff --git a/examples/README.md b/examples/README.md
@@ -17,7 +17,7 @@ The following (random) data should be used when modifying examples:
 ### IDs
 - Artist: ["0LcJLqbBmaGUft1e9Mm8HV"](https://open.spotify.com/artist/0LcJLqbBmaGUft1e9Mm8HV?si=tUHw6JYdQwmE5QIla_7ZaQ)
 - Album: ["5zT1JLIj9E57p3e1rFm9Uq"](https://open.spotify.com/album/5zT1JLIj9E57p3e1rFm9Uq?si=PkAs2KWQTkm2b0vxg_qcRA)
-- Episode: ["4GI3dxEafwap1sFiTGPKd1"](https://open.spotify.com/episode/4GI3dxEafwap1sFiTGPKd1?si=p32KTdx_QTuV2YLatvYkKw)
+- Episode: ["046WGwFKUevqKMA4NQfYUv"](https://open.spotify.com/episode/046WGwFKUevqKMA4NQfYUv?si=p32KTdx_QTuV2YLatvYkKw)
 - Playlist: ["3AGOiaoRXMSjswCLtuNqv5"](https://open.spotify.com/user/abbaspotify/playlist/3AGOiaoRXMSjswCLtuNqv5?si=ru1yCc8QSueG7gHEC7E40w)
 - Track: ["01iyCAUm8EvOFqVWYJ3dVX"](https://open.spotify.com/track/01iyCAUm8EvOFqVWYJ3dVX?si=m0Fdh5ASScyfue6kQerIZg)
 - Show ["5AvwZVawapvyhJUIx71pdJ"](https://open.spotify.com/show/5AvwZVawapvyhJUIx71pdJ?si=TFUPZuTrTS2yF-LD8nIYiw)

diff --git a/...library/CheckUsersSavedAlbumsExample.java → .../albums/CheckUsersSavedAlbumsExample.java b/...library/CheckUsersSavedAlbumsExample.java → .../albums/CheckUsersSavedAlbumsExample.java
@@ -1,8 +1,9 @@
-package data.library;
+package data.albums;
 
 import se.michaelthelin.spotify.SpotifyApi;
 import se.michaelthelin.spotify.exceptions.SpotifyWebApiException;
-import se.michaelthelin.spotify.requests.data.library.CheckUsersSavedAlbumsRequest;
+import se.michaelthelin.spotify.requests.data.albums.CheckUsersSavedAlbumsRequest;
+
 import org.apache.hc.core5.http.ParseException;
 
 import java.io.IOException;

diff --git a/examples/data/albums/GetAlbumsTracksExample.java b/examples/data/albums/GetAlbumsTracksExample.java
@@ -4,7 +4,7 @@
 import se.michaelthelin.spotify.exceptions.SpotifyWebApiException;
 import se.michaelthelin.spotify.model_objects.specification.Paging;
 import se.michaelthelin.spotify.model_objects.specification.TrackSimplified;
-import se.michaelthelin.spotify.requests.data.albums.GetAlbumsTracksRequest;
+import se.michaelthelin.spotify.requests.data.albums.GetAlbumTracksRequest;
 import org.apache.hc.core5.http.ParseException;
 
 import java.io.IOException;
@@ -19,7 +19,7 @@ public class GetAlbumsTracksExample {
   private static final SpotifyApi spotifyApi = new SpotifyApi.Builder()
     .setAccessToken(accessToken)
     .build();
-  private static final GetAlbumsTracksRequest getAlbumsTracksRequest = spotifyApi.getAlbumsTracks(id)
+  private static final GetAlbumTracksRequest getAlbumsTracksRequest = spotifyApi.getAlbumTracks(id)
 //          .limit(10)
 //          .offset(0)
 //          .market(CountryCode.SE)

diff --git a/...ry/GetCurrentUsersSavedAlbumsExample.java → ...ms/GetCurrentUsersSavedAlbumsExample.java b/...ry/GetCurrentUsersSavedAlbumsExample.java → ...ms/GetCurrentUsersSavedAlbumsExample.java
@@ -1,10 +1,11 @@
-package data.library;
+package data.albums;
 
 import se.michaelthelin.spotify.SpotifyApi;
 import se.michaelthelin.spotify.exceptions.SpotifyWebApiException;
 import se.michaelthelin.spotify.model_objects.specification.Paging;
 import se.michaelthelin.spotify.model_objects.specification.SavedAlbum;
-import se.michaelthelin.spotify.requests.data.library.GetCurrentUsersSavedAlbumsRequest;
+import se.michaelthelin.spotify.requests.data.albums.GetUsersSavedAlbumsRequest;
+
 import org.apache.hc.core5.http.ParseException;
 
 import java.io.IOException;
@@ -18,26 +19,26 @@ public class GetCurrentUsersSavedAlbumsExample {
   private static final SpotifyApi spotifyApi = new SpotifyApi.Builder()
     .setAccessToken(accessToken)
     .build();
-  private static final GetCurrentUsersSavedAlbumsRequest getCurrentUsersSavedAlbumsRequest = spotifyApi
-    .getCurrentUsersSavedAlbums()
+  private static final GetUsersSavedAlbumsRequest getUsersSavedAlbumsRequest = spotifyApi
+    .getUsersSavedAlbums()
 //          .limit(10)
 //          .market(CountryCode.SE)
 //          .offset(0)
     .build();
 
-  public static void getCurrentUsersSavedAlbums_Sync() {
+  public static void getUsersSavedAlbums_Sync() {
     try {
-      final Paging<SavedAlbum> savedAlbumPaging = getCurrentUsersSavedAlbumsRequest.execute();
+      final Paging<SavedAlbum> savedAlbumPaging = getUsersSavedAlbumsRequest.execute();
 
       System.out.println("Total: " + savedAlbumPaging.getTotal());
     } catch (IOException | SpotifyWebApiException | ParseException e) {
       System.out.println("Error: " + e.getMessage());
     }
   }
 
-  public static void getCurrentUsersSavedAlbums_Async() {
+  public static void getUsersSavedAlbums_Async() {
     try {
-      final CompletableFuture<Paging<SavedAlbum>> pagingFuture = getCurrentUsersSavedAlbumsRequest.executeAsync();
+      final CompletableFuture<Paging<SavedAlbum>> pagingFuture = getUsersSavedAlbumsRequest.executeAsync();
 
       // Thread free to do other tasks...
 
@@ -53,7 +54,7 @@ public static void getCurrentUsersSavedAlbums_Async() {
   }
 
   public static void main(String[] args) {
-    getCurrentUsersSavedAlbums_Sync();
-    getCurrentUsersSavedAlbums_Async();
+    getUsersSavedAlbums_Sync();
+    getUsersSavedAlbums_Async();
   }
 }