{ "opencollection": "1.0.0", "info": { "name": "SoundStat API", "version": "1.0" }, "request": { "auth": { "type": "apikey", "apikey": { "key": "x-api-key", "value": "{{apiKey}}", "in": "header" } } }, "items": [ { "info": { "name": "Track Analysis", "type": "folder" }, "items": [ { "info": { "name": "Get Track Analysis", "type": "http" }, "http": { "method": "GET", "url": "https://soundstat.info/api/v1/track/:track_id", "params": [ { "name": "track_id", "value": "", "type": "path", "description": "Spotify track ID." } ] }, "docs": "Get detailed audio analysis for a specific track.\n\nParameters:\n----------\ntrack_id : str (Spotify track ID)
\nx_api_key : str (API key for authentication)
\n\nReturns:\n-------\nTrackAnalysis
\n Basic track info (name, artists, genre)
\n Track duration in milliseconds
\n Audio features (tempo, key, mode, energy etc.)
\n\n\nNotes:\n-----\nIf track hasn't been analyzed, initiates analysis and returns processing status." }, { "info": { "name": "Track Status Updates", "type": "http" }, "http": { "method": "GET", "url": "https://soundstat.info/api/v1/track/:track_id/status", "params": [ { "name": "track_id", "value": "", "type": "path", "description": "Spotify track ID." } ] }, "docs": "Get real-time status updates for track analysis via Server-Sent Events (SSE).\n\nParameters:\n----------\ntrack_id : str (Spotify track ID)
\nx_api_key : str (API key for authentication)
\n\nReturns:\n-------\nEventSourceResponse
\n Status updates as SSE events
\n Event types: status, complete, error
\n\nNotes:\n-----\nMaintains an active connection until analysis is complete or fails." } ] }, { "info": { "name": "Search & Discovery", "type": "folder" }, "items": [ { "info": { "name": "Search Tracks", "type": "http" }, "http": { "method": "POST", "url": "https://soundstat.info/api/v1/tracks/search", "params": [ { "name": "genre", "value": "", "type": "query", "description": "optional" }, { "name": "limit", "value": "", "type": "query", "description": "optional" }, { "name": "offset", "value": "", "type": "query", "description": "optional" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Search for analyzed tracks with filtering options.\n\nParameters:\n----------\nx_api_key : str (API key for authentication)
\ngenre : str, optional (Filter by specific genre)
\nlimit : int, default=50 (Maximum number of results, max 100)
\noffset : int, default=0 (Number of results to skip)
\nfilters : AnalysisFilters, optional (Audio feature filters)
\n\nReturns:\n-------\nTrackIDList
\n List of matching track IDs
\n\nNotes:\n-----\nSupports pagination and complex audio feature filtering." }, { "info": { "name": "Get Available Genres", "type": "http" }, "http": { "method": "GET", "url": "https://soundstat.info/api/v1/genres" }, "docs": "Get list of all available genres in the database.\n\nParameters:\n----------\nx_api_key : str (API key for authentication)
\n\nReturns:\n-------\nDict
\n genres: List[str] (List of unique genre names)
\n\nNotes:\n-----\nOnly returns genres that have at least one analyzed track." }, { "info": { "name": "Get Analysis Stats", "type": "http" }, "http": { "method": "GET", "url": "https://soundstat.info/api/v1/stats" }, "docs": "Get comprehensive statistics about analyzed tracks.\n\nParameters:\n----------\nx_api_key : str (API key for authentication)
\n\nReturns:\n-------\nDict
\n general: Dict (Overall statistics)
\n - total_tracks: int
\n - analyzed_tracks: int
\n - unique_genres: int
\n - avg_popularity: float
\n top_genres: List[Dict] (Most common genres)
\n audio_characteristics: Dict (Average audio features)
\n\nNotes:\n-----\nProvides a statistical overview of the analyzed music database." } ] }, { "info": { "name": "Recommendations", "type": "folder" }, "items": [ { "info": { "name": "Get Similar Tracks", "type": "http" }, "http": { "method": "GET", "url": "https://soundstat.info/api/v1/recommendations/similar", "params": [ { "name": "seed_track_id", "value": "", "type": "query", "description": "required" }, { "name": "limit", "value": "", "type": "query", "description": "optional" }, { "name": "min_popularity", "value": "", "type": "query", "description": "optional" }, { "name": "genre_match", "value": "", "type": "query", "description": "optional" } ] }, "docs": "Get track recommendations based on a seed track.\n\nParameters:\n----------\nseed_track_id : str (Spotify ID of the reference track)
\nlimit : int, default=20 (Number of recommendations, max 100)
\nmin_popularity : int, optional (Minimum popularity score 0-100)
\ngenre_match : bool, default=False (Prioritize same genre)
\nx_api_key : str (API key for authentication)
\n\nReturns:\n-------\nTrackIDList
\n List of recommended track IDs
\n\nNotes:\n-----\nUses audio features to find tracks with similar characteristics." }, { "info": { "name": "Get Recommendations By Features", "type": "http" }, "http": { "method": "POST", "url": "https://soundstat.info/api/v1/recommendations/by-features", "body": { "type": "json", "data": "{\n \"limit\": 20\n}" } }, "docs": "Get track recommendations matching specific audio features.\n\nParameters:\n----------\nfeatures : TargetFeatures (Target audio characteristics)
\n - tempo: float, optional (Target BPM, 0-300)
\n - energy: float, optional (Target energy level, 0-1)
\n - danceability: float, optional (Target danceability, 0-1)
\n - duration_ms: int, optional (Target duration in ms, 30000-900000)
\n - other audio features...
\nx_api_key : str (API key for authentication)
\n\nReturns:\n-------\nTrackIDList
\n List of matching track IDs
\n\nNotes:\n-----\nFinds tracks that best match the specified audio characteristics." }, { "info": { "name": "Get Mixed Recommendations", "type": "http" }, "http": { "method": "POST", "url": "https://soundstat.info/api/v1/recommendations/mixed", "body": { "type": "json", "data": "{\n \"seed_tracks\": [\n \"3n3Ppam7vgaVa1iaRUc9Lp\"\n ],\n \"limit\": 20\n}" } }, "docs": "Get Mixed Recommendations" }, { "info": { "name": "Get Progression Recommendations", "type": "http" }, "http": { "method": "POST", "url": "https://soundstat.info/api/v1/recommendations/progression", "body": { "type": "json", "data": "{\n \"parameter\": \"\",\n \"direction\": \"\"\n}" } }, "docs": "Get tracks with progressively changing audio characteristics." }, { "info": { "name": "Get Compatible Tracks", "type": "http" }, "http": { "method": "POST", "url": "https://soundstat.info/api/v1/recommendations/compatible", "body": { "type": "json", "data": "{\n \"track_id\": \"\",\n \"limit\": 20\n}" } }, "docs": "Get tracks that are musically compatible with a reference track.\n\nParameters:\n----------\nparams : CompatibleParams
\n - track_id: str (Reference track ID)
\n - compatibility_type: str, default=\"both\" (key, bpm, both)
\n - limit: int, default=20 (Number of recommendations)
\n - min_popularity: int, optional (Minimum popularity score)
\nx_api_key : str (API key for authentication)
\n\nReturns:\n-------\nTrackIDList
\n List of tracks compatible with the reference track
\n\nNotes:\n-----\nUseful for DJ mixing, creating smooth transitions, or harmonic playlists." }, { "info": { "name": "Get Contrast Recommendations", "type": "http" }, "http": { "method": "POST", "url": "https://soundstat.info/api/v1/recommendations/contrast", "body": { "type": "json", "data": "{\n \"track_id\": \"\",\n \"limit\": 20\n}" } }, "docs": "Get tracks with characteristics contrasting to a reference track.\n\nParameters:\n----------\nparams : ContrastParams
\n - track_id: str (Reference track ID)
\n - contrast_features: List[str], default=[\"energy\", \"valence\"] (Features to contrast)
\n - limit: int, default=20 (Number of recommendations)
\nx_api_key : str (API key for authentication)
\n\nReturns:\n-------\nTrackIDList
\n List of tracks with contrasting characteristics
\n\nNotes:\n-----\nCreates variety in playlists by finding tracks with opposite characteristics." }, { "info": { "name": "Get Cross Genre Recommendations", "type": "http" }, "http": { "method": "POST", "url": "https://soundstat.info/api/v1/recommendations/cross-genre", "body": { "type": "json", "data": "{\n \"track_id\": \"\",\n \"limit\": 20\n}" } }, "docs": "Get tracks from different genres with similar audio characteristics." }, { "info": { "name": "Get Time Of Day Recommendations", "type": "http" }, "http": { "method": "POST", "url": "https://soundstat.info/api/v1/recommendations/time-of-day", "body": { "type": "json", "data": "{\n \"time\": \"evening\",\n \"limit\": 20\n}" } }, "docs": "Get track recommendations suitable for a specific time of day.\n\nParameters:\n----------\nparams : TimeOfDayParams
\n - time: str (One of: morning, afternoon, evening, night)
\n - genre: str, optional (Specific genre filter)
\n - limit: int, default=20 (Number of recommendations)
\nx_api_key : str (API key for authentication)
\n\nReturns:\n-------\nTrackIDList
\n List of recommended track IDs suitable for the time of day
\n\nNotes:\n-----\nDifferent times of day have different energy/mood profiles." }, { "info": { "name": "Get Hidden Gems Recommendations", "type": "http" }, "http": { "method": "POST", "url": "https://soundstat.info/api/v1/recommendations/hidden-gems", "body": { "type": "json", "data": "{\n \"limit\": 20\n}" } }, "docs": "Get recommendations for lesser-known tracks with high-quality audio features." }, { "info": { "name": "Get Beat Structure Recommendations", "type": "http" }, "http": { "method": "POST", "url": "https://soundstat.info/api/v1/recommendations/beat-structure", "body": { "type": "json", "data": "{\n \"limit\": 20\n}" } }, "docs": "Get recommendations for tracks with specific beat structure characteristics.\n\nParameters:\n----------\nparams : BeatStructureParams
\n - min_regularity: float, default=0.7 (Minimum beat regularity score 0-1)
\n - tempo_min: float, optional (Minimum tempo in BPM)
\n - tempo_max: float, optional (Maximum tempo in BPM)
\n - genre: str, optional (Specific genre filter)
\n - limit: int, default=20 (Number of recommendations)
\nx_api_key : str (API key for authentication)
\n\nReturns:\n-------\nTrackIDList
\n List of recommended track IDs matching beat structure criteria
\n\nNotes:\n-----\nUseful for finding tracks with consistent, predictable beat patterns." }, { "info": { "name": "Get Duration Recommendations", "type": "http" }, "http": { "method": "POST", "url": "https://soundstat.info/api/v1/recommendations/duration", "body": { "type": "json", "data": "{\n \"limit\": 20\n}" } }, "docs": "Get track recommendations based on specific duration requirements." }, { "info": { "name": "Get Mood Recommendations", "type": "http" }, "http": { "method": "POST", "url": "https://soundstat.info/api/v1/recommendations/mood", "body": { "type": "json", "data": "{\n \"mood\": \"happy\",\n \"limit\": 20\n}" } }, "docs": "Get track recommendations based on desired mood." }, { "info": { "name": "Get Activity Recommendations", "type": "http" }, "http": { "method": "POST", "url": "https://soundstat.info/api/v1/recommendations/activity", "body": { "type": "json", "data": "{\n \"activity\": \"workout\",\n \"limit\": 20\n}" } }, "docs": "Get track recommendations suitable for specific activities." }, { "info": { "name": "Get Instrumental Recommendations", "type": "http" }, "http": { "method": "POST", "url": "https://soundstat.info/api/v1/recommendations/instrumental", "body": { "type": "json", "data": "{\n \"limit\": 20\n}" } }, "docs": "Get recommendations for instrumental tracks." }, { "info": { "name": "Get Acoustic Recommendations", "type": "http" }, "http": { "method": "POST", "url": "https://soundstat.info/api/v1/recommendations/acoustic", "body": { "type": "json", "data": "{\n \"limit\": 20\n}" } }, "docs": "Get recommendations for acoustic tracks." } ] } ], "bundled": true }