{
"info": {
"name": "SoundStat API",
"description": "SoundStat is an independent music audio-analysis API (a Spotify audio-features alternative). Base URL: https://soundstat.info/api/v1. All requests authenticate with an x-api-key header. Track analysis is billed per unique track; the similar, by-features, and mixed recommendation endpoints are free.",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
},
"auth": {
"type": "apikey",
"apikey": [
{
"key": "key",
"value": "x-api-key",
"type": "string"
},
{
"key": "value",
"value": "{{apiKey}}",
"type": "string"
},
{
"key": "in",
"value": "header",
"type": "string"
}
]
},
"variable": [
{
"key": "baseUrl",
"value": "https://soundstat.info/api/v1",
"type": "string"
},
{
"key": "apiKey",
"value": "",
"type": "string"
}
],
"item": [
{
"name": "Track Analysis",
"item": [
{
"name": "Get Track Analysis",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/track/:track_id",
"host": [
"{{baseUrl}}"
],
"path": [
"track",
":track_id"
]
},
"description": "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."
}
},
{
"name": "Track Status Updates",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/track/:track_id/status",
"host": [
"{{baseUrl}}"
],
"path": [
"track",
":track_id",
"status"
]
},
"description": "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."
}
}
]
},
{
"name": "Search & Discovery",
"item": [
{
"name": "Search Tracks",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"url": {
"raw": "{{baseUrl}}/tracks/search?genre=&limit=&offset=",
"host": [
"{{baseUrl}}"
],
"path": [
"tracks",
"search"
],
"query": [
{
"key": "genre",
"value": "",
"description": "optional"
},
{
"key": "limit",
"value": "",
"description": "optional"
},
{
"key": "offset",
"value": "",
"description": "optional"
}
]
},
"description": "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.",
"body": {
"mode": "raw",
"raw": "{}",
"options": {
"raw": {
"language": "json"
}
}
}
}
},
{
"name": "Get Available Genres",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/genres",
"host": [
"{{baseUrl}}"
],
"path": [
"genres"
]
},
"description": "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."
}
},
{
"name": "Get Analysis Stats",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/stats",
"host": [
"{{baseUrl}}"
],
"path": [
"stats"
]
},
"description": "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."
}
}
]
},
{
"name": "Recommendations",
"item": [
{
"name": "Get Similar Tracks",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/recommendations/similar?seed_track_id=&limit=&min_popularity=&genre_match=",
"host": [
"{{baseUrl}}"
],
"path": [
"recommendations",
"similar"
],
"query": [
{
"key": "seed_track_id",
"value": "",
"description": "required"
},
{
"key": "limit",
"value": "",
"description": "optional"
},
{
"key": "min_popularity",
"value": "",
"description": "optional"
},
{
"key": "genre_match",
"value": "",
"description": "optional"
}
]
},
"description": "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."
}
},
{
"name": "Get Recommendations By Features",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"url": {
"raw": "{{baseUrl}}/recommendations/by-features",
"host": [
"{{baseUrl}}"
],
"path": [
"recommendations",
"by-features"
]
},
"description": "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.",
"body": {
"mode": "raw",
"raw": "{\n \"limit\": 20\n}",
"options": {
"raw": {
"language": "json"
}
}
}
}
},
{
"name": "Get Mixed Recommendations",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"url": {
"raw": "{{baseUrl}}/recommendations/mixed",
"host": [
"{{baseUrl}}"
],
"path": [
"recommendations",
"mixed"
]
},
"description": "Get Mixed Recommendations",
"body": {
"mode": "raw",
"raw": "{\n \"seed_tracks\": [\n \"3n3Ppam7vgaVa1iaRUc9Lp\"\n ],\n \"limit\": 20\n}",
"options": {
"raw": {
"language": "json"
}
}
}
}
},
{
"name": "Get Progression Recommendations",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"url": {
"raw": "{{baseUrl}}/recommendations/progression",
"host": [
"{{baseUrl}}"
],
"path": [
"recommendations",
"progression"
]
},
"description": "Get tracks with progressively changing audio characteristics.",
"body": {
"mode": "raw",
"raw": "{\n \"parameter\": \"\",\n \"direction\": \"\"\n}",
"options": {
"raw": {
"language": "json"
}
}
}
}
},
{
"name": "Get Compatible Tracks",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"url": {
"raw": "{{baseUrl}}/recommendations/compatible",
"host": [
"{{baseUrl}}"
],
"path": [
"recommendations",
"compatible"
]
},
"description": "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.",
"body": {
"mode": "raw",
"raw": "{\n \"track_id\": \"\",\n \"limit\": 20\n}",
"options": {
"raw": {
"language": "json"
}
}
}
}
},
{
"name": "Get Contrast Recommendations",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"url": {
"raw": "{{baseUrl}}/recommendations/contrast",
"host": [
"{{baseUrl}}"
],
"path": [
"recommendations",
"contrast"
]
},
"description": "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.",
"body": {
"mode": "raw",
"raw": "{\n \"track_id\": \"\",\n \"limit\": 20\n}",
"options": {
"raw": {
"language": "json"
}
}
}
}
},
{
"name": "Get Cross Genre Recommendations",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"url": {
"raw": "{{baseUrl}}/recommendations/cross-genre",
"host": [
"{{baseUrl}}"
],
"path": [
"recommendations",
"cross-genre"
]
},
"description": "Get tracks from different genres with similar audio characteristics.",
"body": {
"mode": "raw",
"raw": "{\n \"track_id\": \"\",\n \"limit\": 20\n}",
"options": {
"raw": {
"language": "json"
}
}
}
}
},
{
"name": "Get Time Of Day Recommendations",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"url": {
"raw": "{{baseUrl}}/recommendations/time-of-day",
"host": [
"{{baseUrl}}"
],
"path": [
"recommendations",
"time-of-day"
]
},
"description": "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.",
"body": {
"mode": "raw",
"raw": "{\n \"time\": \"evening\",\n \"limit\": 20\n}",
"options": {
"raw": {
"language": "json"
}
}
}
}
},
{
"name": "Get Hidden Gems Recommendations",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"url": {
"raw": "{{baseUrl}}/recommendations/hidden-gems",
"host": [
"{{baseUrl}}"
],
"path": [
"recommendations",
"hidden-gems"
]
},
"description": "Get recommendations for lesser-known tracks with high-quality audio features.",
"body": {
"mode": "raw",
"raw": "{\n \"limit\": 20\n}",
"options": {
"raw": {
"language": "json"
}
}
}
}
},
{
"name": "Get Beat Structure Recommendations",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"url": {
"raw": "{{baseUrl}}/recommendations/beat-structure",
"host": [
"{{baseUrl}}"
],
"path": [
"recommendations",
"beat-structure"
]
},
"description": "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.",
"body": {
"mode": "raw",
"raw": "{\n \"limit\": 20\n}",
"options": {
"raw": {
"language": "json"
}
}
}
}
},
{
"name": "Get Duration Recommendations",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"url": {
"raw": "{{baseUrl}}/recommendations/duration",
"host": [
"{{baseUrl}}"
],
"path": [
"recommendations",
"duration"
]
},
"description": "Get track recommendations based on specific duration requirements.",
"body": {
"mode": "raw",
"raw": "{\n \"limit\": 20\n}",
"options": {
"raw": {
"language": "json"
}
}
}
}
},
{
"name": "Get Mood Recommendations",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"url": {
"raw": "{{baseUrl}}/recommendations/mood",
"host": [
"{{baseUrl}}"
],
"path": [
"recommendations",
"mood"
]
},
"description": "Get track recommendations based on desired mood.",
"body": {
"mode": "raw",
"raw": "{\n \"mood\": \"happy\",\n \"limit\": 20\n}",
"options": {
"raw": {
"language": "json"
}
}
}
}
},
{
"name": "Get Activity Recommendations",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"url": {
"raw": "{{baseUrl}}/recommendations/activity",
"host": [
"{{baseUrl}}"
],
"path": [
"recommendations",
"activity"
]
},
"description": "Get track recommendations suitable for specific activities.",
"body": {
"mode": "raw",
"raw": "{\n \"activity\": \"workout\",\n \"limit\": 20\n}",
"options": {
"raw": {
"language": "json"
}
}
}
}
},
{
"name": "Get Instrumental Recommendations",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"url": {
"raw": "{{baseUrl}}/recommendations/instrumental",
"host": [
"{{baseUrl}}"
],
"path": [
"recommendations",
"instrumental"
]
},
"description": "Get recommendations for instrumental tracks.",
"body": {
"mode": "raw",
"raw": "{\n \"limit\": 20\n}",
"options": {
"raw": {
"language": "json"
}
}
}
}
},
{
"name": "Get Acoustic Recommendations",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"url": {
"raw": "{{baseUrl}}/recommendations/acoustic",
"host": [
"{{baseUrl}}"
],
"path": [
"recommendations",
"acoustic"
]
},
"description": "Get recommendations for acoustic tracks.",
"body": {
"mode": "raw",
"raw": "{\n \"limit\": 20\n}",
"options": {
"raw": {
"language": "json"
}
}
}
}
}
]
}
]
}