&artist=<artist>` searches the full catalog and queues an on-demand fetch + analysis on a miss; if your own Spotify integration already gives you the ISRC (`external_ids.isrc`), call this same route as `GET /v1/audio-features/<ISRC>` or `GET /lookup?isrc=<ISRC>`.\n\nNotes — the *values* are FreqBlog's own analysis (signal-analysis approximations: directionally compatible with Spotify's ML numbers, not numerically identical — see the [Field-by-Field Threshold Guide](https://freqblog.com/blog/spotify-audio-features-migration-thresholds/) for catalog distribution data and recommended threshold adjustments per field).\n\n**`?calibrate=spotify`** (opt-in) applies a per-field regression fitted on a 5,724-track overlap between our catalog and the public maharshipandya/spotify-tracks-dataset. v1 calibrates `loudness` only (R²=0.43, RMSE 3.0 dB vs raw 8.5 dB — 64% improvement). Other fields fall through unchanged because their heuristic-vs-ML methodology gap is too wide to ship a regression honestly. Default (omit `?calibrate=`) returns raw values.\n\n`analysis_url` is always `null` (no per-segment-analysis analog). For tracks resolved by ISRC, `uri` / `track_href` are `null` and `id` carries the ISRC, since we have no Spotify ID for the recording. Error bodies use FreqBlog's `{\"detail\": …}` shape, not Spotify's `{\"error\": {…}}`. Counts as one quota request. For batches, use the Spotify-shaped sibling: `GET /v1/audio-features?ids=…` (comma-separated, up to 100 IDs).", "operationId": "Audio features", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "A Spotify track ID (22-char base-62, or a `spotify:track:…` URI / open.spotify.com URL) — or an ISRC (12-char, e.g. `USUM71900001`; hyphens optional).", "title": "Identifier" }, "description": "A Spotify track ID (22-char base-62, or a `spotify:track:…` URI / open.spotify.com URL) — or an ISRC (12-char, e.g. `USUM71900001`; hyphens optional)." }, { "name": "calibrate", "in": "query", "required": false, "schema": { "description": "Set to `spotify` (lowercase, exact) to apply Spotify-scale calibration to numeric values. v1 calibrates loudness only (R²=0.43, RMSE 3.0 dB vs raw 8.5 dB — 64% improvement) using a linear regression fitted on a 5,724-track overlap with maharshipandya/spotify-tracks-dataset. Other fields fall through unchanged because their heuristic-vs-ML methodology gap is too wide to calibrate honestly; see the threshold guide for per-field details. Default (omit) returns raw FreqBlog values. Typos / case variants like `Spotify`, `SPOTIFY`, `true`, `1` will 422 — explicit rather than silently returning raw values.", "title": "Calibrate", "nullable": true, "enum": [ "spotify" ], "type": "string" }, "description": "Set to `spotify` (lowercase, exact) to apply Spotify-scale calibration to numeric values. v1 calibrates loudness only (R²=0.43, RMSE 3.0 dB vs raw 8.5 dB — 64% improvement) using a linear regression fitted on a 5,724-track overlap with maharshipandya/spotify-tracks-dataset. Other fields fall through unchanged because their heuristic-vs-ML methodology gap is too wide to calibrate honestly; see the threshold guide for per-field details. Default (omit) returns raw FreqBlog values. Typos / case variants like `Spotify`, `SPOTIFY`, `true`, `1` will 422 — explicit rather than silently returning raw values." } ], "responses": { "200": { "description": "Audio features in Spotify's `AudioFeaturesObject` shape", "content": { "application/json": { "schema": {}, "example": { "acousticness": 0.04, "danceability": 0.76, "duration_ms": 200040, "energy": 0.91, "id": "0VjIjW4GlUZAMYd2vXMi3b", "instrumentalness": 0.02, "key": 1, "liveness": 0.09, "loudness": -7.1, "mode": 0, "speechiness": 0.06, "tempo": 171.0, "time_signature": 4, "track_href": "https://api.spotify.com/v1/tracks/0VjIjW4GlUZAMYd2vXMi3b", "type": "audio_features", "uri": "spotify:track:0VjIjW4GlUZAMYd2vXMi3b", "valence": 0.51 } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No track found for that Spotify track ID / ISRC. This drop-in only covers tracks already mapped to a Spotify ID (a minority of the catalog) — an arbitrary Spotify ID can't be resolved server-side. For reliable coverage, identify the track by name (`GET /lookup?track=<title>&artist=<artist>`, which fetches on a miss) or by ISRC (`GET /lookup?isrc=<ISRC>`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "`identifier` is neither a 22-char Spotify track ID nor a 12-char ISRC", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded, or too many concurrent single-ID lookups for this key (per-key in-flight cap shared with /lookup; carries `Retry-After`). Space requests out, or send a large migration through the batch form `GET /v1/audio-features?ids=…`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The resolve exceeded its internal deadline (kept below the 30s gateway timeout) under load — transient, not a failure. Retry per `Retry-After`, or use the time-boxed batch form `GET /v1/audio-features?ids=…` / `POST /bulk`, which return partial results instead of timing out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/audio-features": { "get": { "tags": [ "Spotify-compat" ], "summary": "Get audio features for several tracks — Spotify-shape compatible (batch)", "description": "**Spotify-shape compatible replacement for the deprecated `GET /v1/audio-features?ids=…`.** Up to **100** comma-separated identifiers per request. Returns `{\"audio_features\": [...]}` — the array length and order match the input; entries are `null` for IDs that don't resolve (matching Spotify's behaviour).\n\nEach `ids` entry is auto-detected exactly like the single-ID route: a 22-char base-62 string → Spotify track ID (also accepts `spotify:track:…` URIs and `open.spotify.com/track/…` URLs); a 12-char ISRC (e.g. `USUM71900001`, hyphens optional) → ISRC lookup. Identifiers that match neither shape fill their slot with `null` rather than failing the whole batch.\n\nAs with the single-ID route, the Spotify-ID drop-in resolves **only tracks already mapped to a Spotify ID** (a minority of the catalog) — an arbitrary Spotify ID can't be reversed to a track server-side, so those slots come back `null`. For reliable coverage, identify tracks by **name or ISRC**: `GET /lookup?track=<title>&artist=<artist>` searches the full catalog and fetches on a miss, and ISRCs (e.g. from your own Spotify integration's `external_ids.isrc`) resolve via the same batch route or `GET /lookup?isrc=<ISRC>`.\n\n**Quota — one token per ID that returns data.** Each resolved ID counts as one quota request; IDs that come back `null` — an unmapped Spotify ID, an ISRC with no match, or one not resolved before the time-box — are **not** charged, exactly like the single-ID route, which is free on a 404 miss. So a 100-ID batch of raw Spotify IDs where only 5 are mapped bills 5, not 100. Spotify billed a 100-ID batch as 1 call; we bill per *resolved* ID, because each resolved lookup runs its own catalog query (and potentially a MusicBrainz roundtrip on an ISRC). See `/pricing` for higher tiers.\n\nOther notes from the single-ID route apply: the *values* are FreqBlog's analysis (signal-analysis approximations, directionally Spotify-compatible — see the [Field-by-Field Threshold Guide](https://freqblog.com/blog/spotify-audio-features-migration-thresholds/) for catalog distribution data and recommended threshold adjustments per field); `analysis_url` is always `null`; errors use FreqBlog's `{\"detail\": …}` shape, not Spotify's `{\"error\": {…}}`.\n\n**Resolved in parallel server-side, bounded for stability.** A large batch of uncatalogued IDs can take a while (each ISRC miss is a MusicBrainz roundtrip); if it exceeds the server time-box you get **partial results** — IDs resolved in time carry features, the rest come back `null` (and aren't charged) and resolve on a retry. A small number of `/bulk` + `/v1/audio-features` batch requests per key run at once — excess get `429` with `Retry-After`.", "operationId": "Audio features (batch)", "parameters": [ { "name": "ids", "in": "query", "required": false, "schema": { "description": "Comma-separated identifiers (max 100). Each is either a Spotify track ID (22-char base-62; also accepts `spotify:track:…` URIs and `open.spotify.com/track/…` URLs) or an ISRC (12-char, e.g. `USUM71900001`; hyphens optional). Only IDs that resolve to data are charged — unmapped IDs return `null` for free. No raw Spotify IDs? Identify tracks by name via `GET /lookup?track=<title>&artist=<artist>`.", "title": "Ids", "nullable": true, "type": "string", "example": "USUM71900001,003vvx7Niy0yvhvHt4a68B,USUMV1902060" }, "description": "Comma-separated identifiers (max 100). Each is either a Spotify track ID (22-char base-62; also accepts `spotify:track:…` URIs and `open.spotify.com/track/…` URLs) or an ISRC (12-char, e.g. `USUM71900001`; hyphens optional). Only IDs that resolve to data are charged — unmapped IDs return `null` for free. No raw Spotify IDs? Identify tracks by name via `GET /lookup?track=<title>&artist=<artist>`." }, { "name": "calibrate", "in": "query", "required": false, "schema": { "description": "Set to `spotify` (lowercase, exact) to apply Spotify-scale calibration to numeric values across the entire batch. Same calibration as the single-ID route: v1 calibrates loudness only (R²=0.43) from a 5,724-track public-dataset overlap. Typos / case variants 422 explicitly.", "title": "Calibrate", "nullable": true, "enum": [ "spotify" ], "type": "string" }, "description": "Set to `spotify` (lowercase, exact) to apply Spotify-scale calibration to numeric values across the entire batch. Same calibration as the single-ID route: v1 calibrates loudness only (R²=0.43) from a 5,724-track public-dataset overlap. Typos / case variants 422 explicitly." } ], "responses": { "200": { "description": "Batch audio features in Spotify's `{audio_features: [...]}` shape; entries are `null` for IDs that don't resolve (Spotify's behaviour)", "content": { "application/json": { "schema": {}, "example": { "audio_features": [ { "acousticness": 0.04, "danceability": 0.76, "energy": 0.91, "id": "0VjIjW4GlUZAMYd2vXMi3b", "key": 1, "mode": 0, "tempo": 171.0, "type": "audio_features", "uri": "spotify:track:0VjIjW4GlUZAMYd2vXMi3b", "...": "(remaining Spotify fields)" }, null, { "id": "USUM71900001", "key": 5, "tempo": 85.39, "type": "audio_features", "track_href": "https://api.freqblog.com/lookup?isrc=USUM71900001", "...": "(remaining Spotify fields)" } ] } } } }, "400": { "description": "`ids` missing, empty, or longer than 100. Supply `?ids=<comma-separated Spotify track IDs or 12-char ISRCs, up to 100>`. No raw Spotify IDs? Identify tracks by name via `GET /lookup?track=<title>&artist=<artist>`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota insufficient, or too many concurrent batch requests for this key (shared with /bulk)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Reserved for genuine service unavailability. The server time-box no longer fails a slow batch — IDs unresolved in time come back `null` in the 200 response (and aren't charged); retry to collect them.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/bulk": { "post": { "tags": [ "Catalog" ], "summary": "Bulk track lookup", "description": "Look up up to 50 tracks in a single request. Identify each item by name (`track`/`artist`) or by `isrc` — or both (`isrc` is matched exactly first, the name is the fallback). At least one of `isrc` or `track` is required (`title` is accepted as an alias for `track`). Because ISRC is exact, it resolves the CJK / K-pop / niche tracks whose fuzzy name-match misses. Each item is otherwise resolved through the same 4-layer fallback chain as `/lookup` (Apple Music catalog → MusicBrainz/AcousticBrainz → FMA Echo Nest → Million Song Dataset), covering 8.5M+ tracks. Tracks not found in any source return `found: false`; the `isrc` you supplied is echoed back on each result so you can map results onto ISRC-keyed inputs.\n\nResolvable-but-uncatalogued items are queued for on-demand ingest straight from the batch (paid plans, bounded per request) so a resolution pass warms the catalogue for your next call.\n\n**Quota** — charged per item that returns features OR queues an on-demand ingest; an ISRC/name with no match anywhere is free, as is one still processing at the 25-second server time-box (slow items come back `found=false` with `backfill_status=\"processing\"` — retry to collect them).", "operationId": "Bulk lookup", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BulkLookupItem" }, "maxItems": 50, "title": "Body" } } } }, "responses": { "200": { "description": "Bulk lookup complete (partial results possible)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkLookupResponse" } } } }, "400": { "description": "Request exceeds 50-track limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded, or too many concurrent /bulk requests for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Reserved for genuine service unavailability. The server time-box no longer fails a slow batch — tracks unresolved in time come back `found=false` with `backfill_status=\"processing\"` in the 200 response (and aren't charged); retry to collect them.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/bpm": { "get": { "tags": [ "Catalog" ], "summary": "Find tracks by BPM", "description": "Return catalog tracks within ±`tolerance` BPM of the target. No audio upload needed — instant lookup from the pre-analyzed catalog.\n\nResults are ordered by proximity to the target BPM, then by popularity. Use `tolerance=0.5` for exact-BPM matching or `tolerance=5` for a wider range.\n\n**Quota**: counts as one request regardless of how many tracks are returned.", "operationId": "Find by BPM", "parameters": [ { "name": "bpm", "in": "query", "required": false, "schema": { "description": "Target BPM", "title": "Bpm", "nullable": true, "type": "number", "maximum": 300.0, "minimum": 20.0 }, "description": "Target BPM" }, { "name": "tolerance", "in": "query", "required": false, "schema": { "type": "number", "maximum": 10.0, "minimum": 0.5, "description": "BPM tolerance window (±BPM)", "default": 2.0, "title": "Tolerance" }, "description": "BPM tolerance window (±BPM)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Maximum tracks to return", "default": 10, "title": "Limit" }, "description": "Maximum tracks to return" } ], "responses": { "200": { "description": "Tracks matching the BPM range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BpmSearchResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Missing or out-of-range `bpm`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/key": { "get": { "tags": [ "Catalog" ], "summary": "Find tracks by musical key", "description": "Return catalog tracks in the specified musical key. Accepts **Camelot** (e.g. `8A`), **Open Key** (e.g. `1m`), or a **key name** (e.g. `A-Minor`, `F#-Major`).\n\nResults are ordered by popularity descending. No audio upload needed — instant lookup from the pre-analyzed catalog.\n\n**Quota**: counts as one request regardless of how many tracks are returned.", "operationId": "Find by key", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 20, "description": "Key query: Camelot (8A), Open Key (1m), or key name (A-Minor)", "title": "Q" }, "description": "Key query: Camelot (8A), Open Key (1m), or key name (A-Minor)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Maximum tracks to return", "default": 10, "title": "Limit" }, "description": "Maximum tracks to return" } ], "responses": { "200": { "description": "Tracks matching the requested key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeySearchResponse" } } } }, "400": { "description": "Unrecognised key format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/search": { "get": { "tags": [ "Catalog" ], "summary": "Search the catalog by track / artist / album", "description": "Full-text search across track name, artist name, and album name. Returns lightweight track stubs (no audio features) ordered by relevance, then popularity. Use `/lookup` to fetch full audio features once you have a track id.\n\nEach whitespace-separated token is matched as a prefix (so `lov dean` matches *'Lover'* by *'Olivia Dean'*). Punctuation in the query is ignored.\n\n**Quota**: counts as one request regardless of how many results are returned.", "operationId": "Search catalog", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Search query (artist, track, album, or any combination).", "title": "Q" }, "description": "Search query (artist, track, album, or any combination)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Maximum results to return.", "default": 10, "title": "Limit" }, "description": "Maximum results to return." } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/artist/tracks": { "get": { "tags": [ "Catalog" ], "summary": "List catalog tracks for an artist", "description": "Returns lightweight track stubs for an artist (case-insensitive exact match on `artist_name`). Use `/search` first if you don't have an exact spelling, or `/lookup` to retrieve full audio features for any single track.\n\nOrdered by popularity descending, then track name. Supports pagination via `limit` + `offset`.\n\n**Quota**: counts as one request regardless of how many tracks are returned.", "operationId": "Artist tracks", "parameters": [ { "name": "artist", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Artist name (case-insensitive exact match).", "title": "Artist" }, "description": "Artist name (case-insensitive exact match)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum tracks to return.", "default": 20, "title": "Limit" }, "description": "Maximum tracks to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Pagination offset.", "default": 0, "title": "Offset" }, "description": "Pagination offset." } ], "responses": { "200": { "description": "Tracks for the requested artist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtistTracksResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No tracks for this artist in the catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/genres": { "get": { "tags": [ "Catalog" ], "summary": "List all genres in the catalog with track counts", "description": "Returns every distinct populated `genre` value in the catalog with the number of tracks tagged. Useful for building filter UIs or discovering coverage gaps.\n\nGenres come from AcousticBrainz (primary) and Last.fm (resolved by the background enrichment pipeline at ingest/backfill time — not on the synchronous lookup path), normalised (e.g. `raphiphop` → `hip-hop`, `folkcountry` → `folk`).\n\n**Quota**: counts as one request.", "operationId": "List genres", "parameters": [ { "name": "min_count", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 10000, "minimum": 1, "description": "Minimum track count for a genre to be included.", "default": 1, "title": "Min Count" }, "description": "Minimum track count for a genre to be included." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "description": "Maximum genres to return.", "default": 200, "title": "Limit" }, "description": "Maximum genres to return." } ], "responses": { "200": { "description": "List of genres in the catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenresResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/genres/{name}/tracks": { "get": { "tags": [ "Catalog" ], "summary": "List catalog tracks tagged with a genre", "description": "Returns lightweight track stubs tagged with the given genre (case-insensitive). Use the `/genres` endpoint to discover available genre names.\n\nOrdered by popularity descending, then track name. Supports pagination via `limit` + `offset`.\n\n**Quota**: counts as one request.", "operationId": "Genre tracks", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "description": "Genre name (case-insensitive).", "title": "Name" }, "description": "Genre name (case-insensitive)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum tracks to return.", "default": 20, "title": "Limit" }, "description": "Maximum tracks to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Pagination offset.", "default": 0, "title": "Offset" }, "description": "Pagination offset." } ], "responses": { "200": { "description": "Tracks tagged with the requested genre", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenreTracksResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No tracks for this genre in the catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/track/{itunes_track_id}/embedding": { "get": { "tags": [ "Catalog" ], "summary": "Numeric feature vector for a track", "description": "Project a track's audio features into a fixed-order numeric vector — convenient for similarity search, clustering, or feeding directly into your own ML model.\n\nThe `fields` array tells you what each position means. The `embedding_mask` array marks which positions came from real analysis (`true`) versus filled with a default (`false`) — use this to ignore filler positions in cosine-similarity calculations.\n\nLook up `itunes_track_id` values via `/search` or from any `/lookup` response.\n\n**Quota**: counts as one request.", "operationId": "Track embedding", "parameters": [ { "name": "itunes_track_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Catalog track id (or `mb:`/`fma:`/`msd:` synthetic id).", "title": "Itunes Track Id" }, "description": "Catalog track id (or `mb:`/`fma:`/`msd:` synthetic id)." } ], "responses": { "200": { "description": "Numeric feature vector for the track", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Track not in catalog or has no audio analysis", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/similar": { "get": { "tags": [ "Catalog" ], "summary": "Find acoustically similar tracks", "description": "Recommendation engine in one call. Pass a seed track id and get back the most acoustically similar tracks in the catalog, ranked by cosine similarity over an 18-feature audio embedding (BPM, key, energy, loudness, danceability, valence, mood, AcousticBrainz descriptors and more).\n\nPer-feature z-score normalisation runs at index build time using only real (non-default) values, so each feature contributes equally regardless of its raw scale. Filler values from missing features contribute zero to similarity — tracks with little real data don't poison the rankings.\n\n**Pass `track_id`** from any prior `/lookup`, `/search`, or `/bpm` response. Use `exclude_same_artist=true` to filter out other tracks by the same artist (useful for cross-artist recommendation feeds).\n\n**Quota**: counts as one request regardless of how many tracks are returned.", "operationId": "Similar tracks", "parameters": [ { "name": "track_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Seed track id (the catalog `itunes_track_id` from any prior response).", "title": "Track Id" }, "description": "Seed track id (the catalog `itunes_track_id` from any prior response)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Maximum results to return.", "default": 10, "title": "Limit" }, "description": "Maximum results to return." }, { "name": "exclude_same_artist", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Drop other tracks by the same artist as the seed.", "default": false, "title": "Exclude Same Artist" }, "description": "Drop other tracks by the same artist as the seed." } ], "responses": { "200": { "description": "Tracks ranked by audio-feature similarity to the seed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimilarResponse" } } } }, "400": { "description": "Seed track has too few real features to recommend from.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Seed track not found in catalog (or has no analysis).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/charts/{country}": { "get": { "tags": [ "Catalog" ], "summary": "Live national music chart (Apple Music)", "description": "Live top-songs chart for any of 45 supported countries, sourced from Apple Music RSS. Each entry is cross-referenced against the FreqBlog catalog — when the track is already analysed, `in_catalog=true` and `catalog_track` is populated with the full TrackStub (including `itunes_track_id` you can pass straight to `/lookup`, `/similar` or `/track/{id}/embedding`).\n\nSnapshots are cached for 12 hours per country/type/limit, so calling this is cheap.\n\n**Quota**: counts as one request.", "operationId": "National chart", "parameters": [ { "name": "country", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code, lowercase (e.g. `gb`, `us`, `jp`).", "title": "Country" }, "description": "ISO 3166-1 alpha-2 country code, lowercase (e.g. `gb`, `us`, `jp`)." }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "description": "Chart type: `most-played` (default) or `new-music`.", "default": "most-played", "title": "Type" }, "description": "Chart type: `most-played` (default) or `new-music`." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum chart entries to return.", "default": 50, "title": "Limit" }, "description": "Maximum chart entries to return." } ], "responses": { "200": { "description": "Live Apple Music chart for the country", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChartResponse" } } } }, "400": { "description": "Unsupported country code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream Apple RSS error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/radio": { "get": { "tags": [ "Catalog" ], "summary": "Generate a harmonic + BPM-continuity radio playlist", "description": "Build a continuous DJ-style playlist starting from a seed track. The walk is greedy: at each step we pick the most similar candidate that also satisfies harmonic mixing rules (Camelot wheel adjacency ≤ `max_key_distance`) and BPM continuity (within ±`bpm_drift` of the previous track).\n\nReturned tracks are in play order — the first entry equals the seed. Use this output directly with the export endpoints (`/export/rekordbox?track_ids=...`) to send a ready-to-mix playlist into Rekordbox or Serato.\n\n**Quota**: counts as one request regardless of `n`.", "operationId": "Radio playlist", "parameters": [ { "name": "seed_track_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Seed track id (catalog `itunes_track_id`).", "title": "Seed Track Id" }, "description": "Seed track id (catalog `itunes_track_id`)." }, { "name": "n", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 2, "description": "Total playlist length including the seed.", "default": 20, "title": "N" }, "description": "Total playlist length including the seed." }, { "name": "max_key_distance", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 12, "minimum": 0, "description": "Maximum Camelot-wheel hops between consecutive tracks. 1 = strict (same/adjacent/relative); 2 = relaxed; ≥3 = effectively no key constraint.", "default": 2, "title": "Max Key Distance" }, "description": "Maximum Camelot-wheel hops between consecutive tracks. 1 = strict (same/adjacent/relative); 2 = relaxed; ≥3 = effectively no key constraint." }, { "name": "bpm_drift", "in": "query", "required": false, "schema": { "type": "number", "maximum": 30.0, "minimum": 0.5, "description": "Max BPM difference between consecutive tracks.", "default": 8.0, "title": "Bpm Drift" }, "description": "Max BPM difference between consecutive tracks." }, { "name": "exclude_same_artist", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Drop tracks by the seed's artist from the entire playlist.", "default": false, "title": "Exclude Same Artist" }, "description": "Drop tracks by the seed's artist from the entire playlist." } ], "responses": { "200": { "description": "Harmonic playlist starting from the seed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadioResponse" } } } }, "400": { "description": "Seed has too little data to build a radio playlist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Seed track not in catalog (no audio analysis)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/transition": { "get": { "tags": [ "Catalog" ], "summary": "Score how well two tracks mix (harmonic + tempo + energy)", "description": "Score the transition FROM `from_track_id` INTO `to_track_id` on a 0-100 scale, blending Camelot-wheel key compatibility, octave-aware BPM proximity (half/double time counts), and energy smoothness — with a plain-English `reason`. This is set *flow*, not raw key/BPM — no competitor exposes pairwise transition scoring as an API.\n\nThe overall score is `0.50·harmonic + 0.30·tempo + 0.20·energy`. A missing key or BPM on a row doesn't hard-fail — the affected component falls back to a neutral 50 and `detail.key_relation` is reported as `unknown`.\n\nFind `itunes_track_id`s via `/search` or any `/lookup` response; chain `/next-track` → `/transition` → `/export/rekordbox`.\n\n**Quota**: counts as one request.", "operationId": "Score transition", "parameters": [ { "name": "from_track_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Track you're mixing OUT of (catalog `itunes_track_id`, or a `mb:`/`fma:`/`msd:` synthetic id).", "title": "From Track Id" }, "description": "Track you're mixing OUT of (catalog `itunes_track_id`, or a `mb:`/`fma:`/`msd:` synthetic id)." }, { "name": "to_track_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Track you're mixing INTO (catalog `itunes_track_id`, or a `mb:`/`fma:`/`msd:` synthetic id).", "title": "To Track Id" }, "description": "Track you're mixing INTO (catalog `itunes_track_id`, or a `mb:`/`fma:`/`msd:` synthetic id)." } ], "responses": { "200": { "description": "Mix-compatibility score for the from→to transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransitionResponse" } } } }, "400": { "description": "`from_track_id` and `to_track_id` are the same", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "One of the track ids is not in the catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/next-track": { "get": { "tags": [ "Catalog" ], "summary": "Ranked next-track suggestions for a seed (harmonic + tempo + energy)", "description": "Given a seed track, return the tracks that mix best after it: the seed's closest sonic neighbours, re-ranked by transition score (Camelot key + octave-aware BPM + energy). Each suggestion carries its overall score, the harmonic/tempo/energy component breakdown, and a plain-English `reason`.\n\nUse `min_score` to keep only clean mixes; `bpm_drift` and `max_key_distance` constrain the candidate pool before scoring. Find the seed `itunes_track_id` via `/search` or any `/lookup` response; chain the picks into `/transition` or `/export/rekordbox`.\n\n**Quota**: counts as 3 requests (it scores a large candidate pool).", "operationId": "Next track", "parameters": [ { "name": "seed_track_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Seed track id (catalog `itunes_track_id`).", "title": "Seed Track Id" }, "description": "Seed track id (catalog `itunes_track_id`)." }, { "name": "n", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Number of suggestions to return.", "default": 10, "title": "N" }, "description": "Number of suggestions to return." }, { "name": "min_score", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 0, "description": "Drop suggestions scoring below this overall value.", "default": 0, "title": "Min Score" }, "description": "Drop suggestions scoring below this overall value." }, { "name": "exclude_same_artist", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Skip tracks by the seed's artist.", "default": false, "title": "Exclude Same Artist" }, "description": "Skip tracks by the seed's artist." }, { "name": "bpm_drift", "in": "query", "required": false, "schema": { "type": "number", "maximum": 60.0, "minimum": 0.5, "description": "Max BPM difference (octave-aware) for a candidate to be considered.", "default": 12.0, "title": "Bpm Drift" }, "description": "Max BPM difference (octave-aware) for a candidate to be considered." }, { "name": "max_key_distance", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 12, "minimum": 0, "description": "Max Camelot-wheel hops for a candidate. 12 = no key constraint.", "default": 2, "title": "Max Key Distance" }, "description": "Max Camelot-wheel hops for a candidate. 12 = no key constraint." }, { "name": "cross_genre", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "auto", "allow", "strict" ], "description": "Genre handling. 'auto' (default) keeps picks in a mixable genre lane — an off-genre track that only coincidentally shares the key + BPM sinks to the bottom and appears only if too few in-genre picks exist. 'strict' = same genre-family only. 'allow' = genre-blind (pure harmonic + tempo + energy).", "default": "auto", "title": "Cross Genre" }, "description": "Genre handling. 'auto' (default) keeps picks in a mixable genre lane — an off-genre track that only coincidentally shares the key + BPM sinks to the bottom and appears only if too few in-genre picks exist. 'strict' = same genre-family only. 'allow' = genre-blind (pure harmonic + tempo + energy)." } ], "responses": { "200": { "description": "Ranked next-track suggestions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NextTrackResponse" } } } }, "400": { "description": "Seed has too little data to rank from", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Seed track not in catalog / similarity index", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Similarity index not yet built; try again shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/setlist": { "post": { "tags": [ "Catalog" ], "summary": "Order a crate into a beat-matched, energy-arced set", "description": "Give it a crate of catalog `itunes_track_id`s and it returns them **ordered** into a continuous set: each consecutive pair is harmonically + tempo compatible, and the set's energy follows the chosen `arc` (`peak_time` builds to a late peak then eases; `warmup` rises; `cooldown` falls; `flat` just optimises for smooth mixing). Greedy placement maximises transition score minus distance from the arc's energy target at each step.\n\nReturns the ordered `tracks`, the per-step `transitions` (with scores + reasons), and an overall `flow_score`. Chain into `/export/rekordbox?track_ids=...` (in the returned order) to drop the set straight into Rekordbox/Serato. Ids not in the catalog are returned in `omitted` and skipped.\n\n**Quota**: counts as 5 requests (it scores every candidate pair).", "operationId": "Build setlist", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetlistRequest" } } } }, "responses": { "200": { "description": "Tracks ordered into a beat-matched, energy-arced set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetlistResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "None of the supplied track ids are in the catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid body — need 2-100 `track_ids` and a known `arc` shape", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/export/{format}": { "get": { "tags": [ "Catalog" ], "summary": "Export tracks as a DJ playlist (Rekordbox / Serato / M3U / cuesheet)", "description": "Generate a DJ-ready file from a list of catalog `itunes_track_id`s.\n\n**Formats:**\n- `rekordbox` — Pioneer Rekordbox XML 1.0.0. Hot cue at the chorus / drop position. Most DJ software supports this format directly (Rekordbox, Engine DJ, Serato via XML import).\n- `m3u` — Extended M3U8 with BPM + Camelot in each EXTINF title. Read by Serato, Traktor, VirtualDJ, Engine DJ.\n- `cuesheet` — Plain-text cue sheet. Easy to paste into a notebook or share over chat.\n\nPair with `/radio?seed_track_id=...` to generate a harmonic playlist, then export it to your DJ software in one chained call.\n\n**Note:** the `Location` field references a synthetic path (`freqblog://<id>`); after import, relink each track to your local audio library — DJ software has built-in tools for this.\n\n**Quota**: counts as one request.", "operationId": "Export playlist", "parameters": [ { "name": "format", "in": "path", "required": true, "schema": { "type": "string", "description": "Output format: `rekordbox`, `m3u`, or `cuesheet`.", "title": "Format" }, "description": "Output format: `rekordbox`, `m3u`, or `cuesheet`." }, { "name": "track_ids", "in": "query", "required": true, "schema": { "type": "string", "description": "Comma-separated list of catalog `itunes_track_id`s, in playlist order.", "title": "Track Ids" }, "description": "Comma-separated list of catalog `itunes_track_id`s, in playlist order." } ], "responses": { "200": { "description": "DJ-ready file (XML / M3U / text).", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Unknown format or no track ids supplied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "None of the requested track ids are in the catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/bulk-csv": { "post": { "tags": [ "Catalog" ], "summary": "Bulk-enrich a CSV of (artist, title) pairs", "description": "Upload a CSV with `artist,title` columns and receive an enriched CSV with the full audio-features set appended to each row — BPM, key, mood, valence, danceability, energy, ISRC, MBID, and 28 more.\n\nHeader row is required and must contain `artist` and `title` (case-insensitive). Extra columns in the input are preserved in the output untouched.\n\n**Capacity**: up to 500 rows per request. Tracks not in the catalog or fallback chain return empty audio columns. Each data row with an artist and title counts as one quota request — headroom is verified before processing (`429` if the file is larger than your remaining quota) and charged only after the enrichment completes; a timed-out request (`503`) is never billed.\n\nForm field name: `file` (multipart/form-data).", "operationId": "Bulk CSV enrich", "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_bulk_csv_endpoint_bulk_csv_post" } } } }, "responses": { "200": { "description": "Enriched CSV with audio features per row.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "CSV parse error or no data rows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "More than 500 rows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota insufficient for the number of rows in the file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Enrichment timed out server-side and was cancelled — no quota charged. Split the file and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/track/{itunes_track_id}/artwork": { "get": { "tags": [ "Catalog" ], "summary": "Cover art for a track", "description": "302-redirect to a cover-art image for the track. Resolution order: iTunes Lookup API for numeric catalog ids, then Cover Art Archive via the track's MusicBrainz release IDs. The first hit is cached for 30 days (misses are also cached so we don't pummel upstream services).\n\n**Sizes**: 100, 200, 250, 300, 500, 600, 1000, 1200 — the closest supported size is used; iTunes URLs accept any of these, Cover Art Archive supports 250/500/1200.\n\n**Quota**: counts as one request.", "operationId": "Track cover art", "parameters": [ { "name": "itunes_track_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Catalog track id (numeric iTunes id, or `mb:`/`fma:`/`msd:`/`apple_<hash>` synthetic id).", "title": "Itunes Track Id" }, "description": "Catalog track id (numeric iTunes id, or `mb:`/`fma:`/`msd:`/`apple_<hash>` synthetic id)." }, { "name": "size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1200, "minimum": 100, "description": "Desired image size in pixels (square).", "default": 300, "title": "Size" }, "description": "Desired image size in pixels (square)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "302": { "description": "Redirect to the actual cover-art image." }, "400": { "description": "Invalid `size` parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No cover art available for this track.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/track/{itunes_track_id}/lyrics": { "get": { "tags": [ "Catalog" ], "summary": "Lyrics (plain + synced) for a catalog track", "description": "Returns synced + plain lyrics for a track via the open **LRClib** dataset. Lyrics are cached for 30 days per (track, artist) pair; cache misses are also cached so we don't repeatedly hit LRClib for tracks they don't have.\n\nSynced lyrics come back parsed: each entry is `{ms: int, text: str}` so you don't have to do LRC math client-side. Instrumentals return `instrumental: true` with empty lyrics arrays.\n\n**Quota**: counts as one request.", "operationId": "Track lyrics", "parameters": [ { "name": "itunes_track_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Catalog `itunes_track_id`.", "title": "Itunes Track Id" }, "description": "Catalog `itunes_track_id`." } ], "responses": { "200": { "description": "Lyrics payload (plain + synced) or instrumental flag.", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lyrics found for this track", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/track/{itunes_track_id}/waveform.svg": { "get": { "tags": [ "Catalog" ], "summary": "SVG waveform for a track", "description": "Returns an SVG waveform render of the track's 30-second iTunes preview. The bucketed RMS values are cached for 90 days; SVG rendering happens at request time so callers can request any width/height without re-decoding audio.\n\nUse `currentColor` in your CSS to theme the waveform — every bar inherits the parent element's text colour. Defaults: 600×80.\n\nOnly works for catalog tracks with a numeric iTunes track id (the preview URL comes from iTunes Lookup). Synthetic ids (`mb:`/`fma:`/`msd:`/`apple_<hash>`) return 404.\n\n**Quota**: counts as one request.", "operationId": "Track waveform", "parameters": [ { "name": "itunes_track_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Numeric catalog `itunes_track_id`.", "title": "Itunes Track Id" }, "description": "Numeric catalog `itunes_track_id`." }, { "name": "w", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 2400, "minimum": 120, "description": "SVG width in pixels.", "default": 600, "title": "W" }, "description": "SVG width in pixels." }, { "name": "h", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 400, "minimum": 20, "description": "SVG height in pixels.", "default": 80, "title": "H" }, "description": "SVG height in pixels." } ], "responses": { "200": { "description": "SVG waveform image.", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No audio preview available for this track", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/recommendations": { "get": { "tags": [ "Catalog" ], "summary": "Recommended tracks for seed tracks (Spotify /recommendations replacement)", "description": "**The drop-in for Spotify's removed `GET /v1/recommendations`** (deprecated November 2024, fully retired since). Supply 1-5 catalog `itunes_track_id`s as `seed_tracks`; we blend them into a single point in audio-feature space (a centroid over an 18-feature embedding — BPM, key, energy, loudness, danceability, valence, mood, AcousticBrainz descriptors and more) and return the nearest catalogue tracks, **re-ranked by genre affinity** so a feature-close cross-genre track doesn't outrank same-genre picks.\n\nBuilt on FreqBlog's own audio-feature similarity index + catalogue genre (94% coverage) — no Spotify account, no deprecated endpoint, no ListenBrainz dependency. Seeds are FreqBlog `itunes_track_id`s (e.g. `apple_ad1829eeccb70f9a`), taken from `/search` or any `/lookup` response.\n\n`score` is the raw audio-feature cosine similarity (genre affinity influences **ordering**, not the score), so the returned list is **not** strictly score-descending. Each seed is echoed back in `seeds` with a `found` flag so you can tell which ids were usable.\n\n**No id?** Pass `track` + `artist` instead of `seed_tracks` and we resolve the name to the best catalogue match (echoed back as `seed_query` so you can confirm it) and seed on it; `seed_tracks` wins if both are sent. A name we don't yet have returns 404 — `/lookup` it first.\n\n**Quota**: counts as 2 requests.", "operationId": "Recommendations", "parameters": [ { "name": "seed_tracks", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma-separated catalog `itunes_track_id`s (1-5). Recommendations are based on their blended feature-space centroid. Omit and use `track`(+`artist`) to seed by name instead.", "title": "Seed Tracks", "example": "apple_ad1829eeccb70f9a" }, "description": "Comma-separated catalog `itunes_track_id`s (1-5). Recommendations are based on their blended feature-space centroid. Omit and use `track`(+`artist`) to seed by name instead." }, { "name": "track", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200, "description": "Seed by track NAME instead of an id — resolved to the best catalogue match (echoed back as `seed_query`). Pair with `artist` to disambiguate. Ignored when `seed_tracks` is supplied.", "title": "Track", "example": "Got to Be Real" }, "description": "Seed by track NAME instead of an id — resolved to the best catalogue match (echoed back as `seed_query`). Pair with `artist` to disambiguate. Ignored when `seed_tracks` is supplied." }, { "name": "artist", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200, "description": "Artist name narrowing the `track` seed (case-insensitive).", "title": "Artist", "example": "Cheryl Lynn" }, "description": "Artist name narrowing the `track` seed (case-insensitive)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Number of recommendations to return.", "default": 20, "title": "Limit" }, "description": "Number of recommendations to return." }, { "name": "exclude_seed_artists", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Drop tracks by any of the seed artists from the results.", "default": false, "title": "Exclude Seed Artists" }, "description": "Drop tracks by any of the seed artists from the results." }, { "name": "cross_genre", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "auto", "allow", "strict" ], "description": "Genre handling. 'auto' (default) re-ranks by genre affinity so a feature-close cross-genre track can't outrank same-genre picks, while cross-genre picks still appear (result never shorter). 'strict' = same genre-family only (off-genre matches dropped server-side). 'allow' = genre-blind (pure audio-feature cosine).", "default": "auto", "title": "Cross Genre" }, "description": "Genre handling. 'auto' (default) re-ranks by genre affinity so a feature-close cross-genre track can't outrank same-genre picks, while cross-genre picks still appear (result never shorter). 'strict' = same genre-family only (off-genre matches dropped server-side). 'allow' = genre-blind (pure audio-feature cosine)." } ], "responses": { "200": { "description": "Recommended tracks for the seed blend", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecommendationsResponse" } } } }, "400": { "description": "No seed supplied — provide `seed_tracks` (1-5 catalog track ids) or a `track` name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "None of the seed tracks are in the catalog (or have enough audio features) to recommend from", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Similarity index not yet built — try again shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/related-artists": { "get": { "tags": [ "Catalog" ], "summary": "Artists related to a seed artist (Spotify related-artists replacement)", "description": "**The drop-in for Spotify's removed `GET /v1/artists/{id}/related-artists`** (deprecated November 2024, fully retired since). Pass an artist `name`; since no artist graph exists we derive one on the fly: we build the seed artist's track-vector centroid from their catalogue tracks, find the nearest tracks in audio-feature space, then aggregate those by artist.\n\nEach candidate artist is scored on its **top-3 track similarities** (so a prolific catalogue artist can't dominate purely on volume) plus a same-genre lift and a cross-genre penalty. Built on FreqBlog's own similarity index + catalogue genre (94% coverage) — no Spotify account, no artist-relations graph required.\n\nEach result carries a `sample_track_id` you can feed straight to `/lookup`, `/similar`, or `/next-track`. Real example: `/related-artists?artist=Van%20Halen` leads with Danger Danger, AC/DC, Def Leppard.\n\n**Quota**: counts as 2 requests.", "operationId": "Related artists", "parameters": [ { "name": "artist", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Seed artist name (as it appears in the catalog; case-insensitive).", "title": "Artist", "example": "Van Halen" }, "description": "Seed artist name (as it appears in the catalog; case-insensitive)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Number of related artists to return.", "default": 20, "title": "Limit" }, "description": "Number of related artists to return." } ], "responses": { "200": { "description": "Artists related to the seed artist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelatedArtistsResponse" } } } }, "400": { "description": "No artist supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Seed artist not found in the catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Similarity index not yet built — try again shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/tag": { "get": { "tags": [ "Catalog" ], "summary": "Compact descriptive tags for a track (mood / energy / genre, with provenance)", "description": "Returns a compact, **honestly-labelled** tag array for a track — a tag-shaped projection of the same open-data analysis `/lookup` returns (no upload, no extra compute). Resolve by exactly ONE of `track`(+`artist`), `isrc`, `mbid`, `spotify_id`, or catalog `track_id`.\n\nEvery tag carries a `confidence` (`measured` = our Essentia analysis | `derived` = MIREX mood from valence+energy | `model-estimated` = AcousticBrainz mood SVM probability, raw prob in `value` | `catalog-genre` = broad catalogue tag) and a `provenance` — the honesty is the point, vs opaque taggers. `value` is the [0,1] score for numeric tags, null for label-only tags.\n\nThe broad, reliable coverage is the MEASURED tags from our analysis (the analysed catalogue + on-demand by name); MBID/ISRC additionally reach 7.5M+ AcousticBrainz recordings WHEN you supply that identifier. For the full numeric feature set use `/lookup`; for nearest tracks use `/similar`.\n\n**Quota**: 1 request.", "operationId": "Tag", "parameters": [ { "name": "track", "in": "query", "required": false, "schema": { "type": "string", "title": "Track", "description": "Track name. Supply this OR `isrc`/`mbid`/`spotify_id`/`track_id`." }, "description": "Track name. Supply this OR `isrc`/`mbid`/`spotify_id`/`track_id`." }, { "name": "artist", "in": "query", "required": false, "schema": { "type": "string", "title": "Artist", "description": "Artist name (narrows `track`; required when `track` ≤2 chars)." }, "description": "Artist name (narrows `track`; required when `track` ≤2 chars)." }, { "name": "isrc", "in": "query", "required": false, "schema": { "type": "string", "title": "Isrc", "description": "ISRC, e.g. `USUM71900001`." }, "description": "ISRC, e.g. `USUM71900001`." }, { "name": "mbid", "in": "query", "required": false, "schema": { "type": "string", "title": "Mbid", "description": "MusicBrainz recording ID (UUID) — tags read straight from AcousticBrainz for that recording." }, "description": "MusicBrainz recording ID (UUID) — tags read straight from AcousticBrainz for that recording." }, { "name": "spotify_id", "in": "query", "required": false, "schema": { "type": "string", "title": "Spotify Id", "description": "Spotify track ID — resolves ONLY tracks already mapped to a Spotify ID (~2.4% of the catalog); prefer track (+artist) or isrc for full coverage." }, "description": "Spotify track ID — resolves ONLY tracks already mapped to a Spotify ID (~2.4% of the catalog); prefer track (+artist) or isrc for full coverage." }, { "name": "track_id", "in": "query", "required": false, "schema": { "type": "string", "title": "Track Id", "description": "Catalog `itunes_track_id` (from `/search` or any `/lookup`)." }, "description": "Catalog `itunes_track_id` (from `/search` or any `/lookup`)." } ], "responses": { "200": { "description": "Tags for the resolved track", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagResponse" } } } }, "400": { "description": "Short track name needs an `artist`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Track not found or not yet analysed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Supply exactly one identifier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "schemas": { "ArtistTracksResponse": { "properties": { "artist": { "type": "string", "title": "Artist", "description": "Artist name as submitted (case preserved)." }, "total": { "type": "integer", "title": "Total", "description": "Total tracks in catalog for this artist (independent of `limit`/`offset`)." }, "count": { "type": "integer", "title": "Count", "description": "Number of tracks in this response page." }, "tracks": { "items": { "$ref": "#/components/schemas/TrackStub" }, "type": "array", "title": "Tracks" } }, "type": "object", "required": [ "artist", "total", "count", "tracks" ], "title": "ArtistTracksResponse" }, "AudioAnalysisResponse": { "properties": { "bpm": { "type": "number", "maximum": 300.0, "minimum": 20.0, "title": "Bpm", "description": "Tempo in beats per minute. Equivalent to Spotify's `tempo` field.", "example": 128.0 }, "bpm_alt": { "title": "Bpm Alt", "description": "Half-time/double-time corrected alternative BPM, when our heuristic suggests the detected `bpm` may be off by a factor of 2. Null when no correction is warranted. Never replaces `bpm`.", "nullable": true, "type": "number", "example": 256.0 }, "bpm_confidence": { "type": "number", "title": "Bpm Confidence", "description": "Beat-strength score from Essentia's RhythmExtractor2013. Higher = stronger rhythmic pulse. Typical range 0–10. Values below 1.0 indicate weak or absent rhythm (ambient, spoken word).", "example": 4.12 }, "key": { "type": "string", "title": "Key", "description": "Musical key and scale as a human-readable string, e.g. `A-Minor` or `F#-Major`. Combines Spotify's integer `key` + `mode` fields into one readable value.", "example": "A-Minor" }, "key_confidence": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Key Confidence", "description": "Key detection confidence [0–1]. Below 0.4 indicates atonal, modal, or harmonically ambiguous content. Equivalent to Spotify's implicit key reliability.", "example": 0.83 }, "mode": { "title": "Mode", "description": "Musical mode as a Spotify-compatible integer: `0` = minor, `1` = major. Direct drop-in for Spotify's deprecated `mode` field.", "nullable": true, "type": "integer", "maximum": 1.0, "minimum": 0.0, "example": 0 }, "key_int": { "title": "Key Int", "description": "Pitch-class integer for the key, Spotify-compatible: `0` = C, `1` = C♯/D♭, `2` = D, … `11` = B. `null` when the key is undetected/atonal (Spotify used `-1`).", "nullable": true, "type": "integer", "maximum": 11.0, "minimum": 0.0, "example": 1 }, "camelot": { "title": "Camelot", "description": "Camelot wheel notation for harmonic mixing, e.g. `8A` (A-Minor) or `5B` (D-Major). Used by DJs to find harmonically compatible tracks. A = minor keys, B = major keys. Numbers 1–12.", "nullable": true, "type": "string", "example": "8A" }, "open_key": { "title": "Open Key", "description": "Open Key notation for harmonic mixing, e.g. `1m` (A-Minor) or `1d` (C-Major). Alternative to Camelot — used by Serato DJ and Mixed In Key. d = major (dominant), m = minor. Numbers 1–12.", "nullable": true, "type": "string", "example": "1m" }, "acousticness": { "title": "Acousticness", "description": "Confidence that the track is acoustic [0–1]. Derived from spectral flatness — low flatness = more tonal/acoustic. Equivalent to Spotify's `acousticness` field.", "nullable": true, "type": "number", "maximum": 1.0, "minimum": 0.0, "example": 0.21 }, "danceability": { "title": "Danceability", "description": "How suitable the track is for dancing [0–1]. Based on tempo (peaks at 120 BPM), beat strength, and rhythmic regularity. Equivalent to Spotify's `danceability` field.", "nullable": true, "type": "number", "maximum": 1.0, "minimum": 0.0, "example": 0.78 }, "instrumentalness": { "title": "Instrumentalness", "description": "Likelihood the track contains no vocals [0–1]. Derived from MFCC variance in vocal-formant frequency ranges. Equivalent to Spotify's `instrumentalness` field.", "nullable": true, "type": "number", "maximum": 1.0, "minimum": 0.0, "example": 0.04 }, "liveness": { "title": "Liveness", "description": "Likelihood the track was performed live [0–1]. Derived from the noise floor ratio (audience/room ambience proxy). Equivalent to Spotify's `liveness` field.", "nullable": true, "type": "number", "maximum": 1.0, "minimum": 0.0, "example": 0.09 }, "speechiness": { "title": "Speechiness", "description": "Presence of spoken words [0–1]. Derived from zero-crossing rate — high ZCR indicates speech or rap. Equivalent to Spotify's `speechiness` field.", "nullable": true, "type": "number", "maximum": 1.0, "minimum": 0.0, "example": 0.06 }, "valence": { "title": "Valence", "description": "Musical positiveness [0–1]. High = happy/euphoric, low = sad/dark. Derived from scale (major/minor), tempo, spectral brightness, and energy. Equivalent to Spotify's `valence` field.", "nullable": true, "type": "number", "maximum": 1.0, "minimum": 0.0, "example": 0.54 }, "mood": { "title": "Mood", "description": "MIREX-style mood category derived from valence and energy. One of: happy, calm, sad, tense, energetic, melancholic, neutral. Maps the four-quadrant mood model: high valence + high energy = happy; low valence + high energy = tense; etc.", "nullable": true, "type": "string", "example": "happy" }, "representative_segment_start": { "title": "Representative Segment Start", "description": "Start time in seconds of the highest-energy 30-second window. Identifies the most sonically representative (e.g. chorus or drop) segment. Useful for sync licensing, preview generation, and waveform thumbnails. 0.0 for tracks ≤ 30 s.", "nullable": true, "type": "number", "example": 62.0 }, "rms_energy": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Rms Energy", "description": "Normalised RMS loudness [0–1]. Comparable to Spotify's `energy` field — both measure perceptual intensity. Computed over the same 30-second window as BPM and key.", "example": 0.74 }, "loudness_db": { "title": "Loudness Db", "description": "Integrated loudness in dBFS (decibels relative to full scale). Equivalent to Spotify's `loudness` field. Typical mastered pop/electronic: -10 to -5 dBFS. Quiet/acoustic: -20 to -15.", "nullable": true, "type": "number", "example": -7.4 }, "time_signature": { "title": "Time Signature", "description": "Estimated time signature (bar grouping). Equivalent to Spotify's `time_signature` field. Most tracks return 4 (4/4). Values: 2, 3, 4, 5, 6, 7.", "nullable": true, "type": "integer", "example": 4 }, "mood_vector": { "title": "Mood Vector", "description": "Dimensional mood scores [0–1] across five axes: `happy`, `sad`, `aggressive`, `relaxed`, `party`. Populated when an AcousticBrainz high-level match is found; `null` otherwise. Use these for fine-grained mood filtering beyond the single-label `mood` field.", "nullable": true, "additionalProperties": { "type": "number" }, "type": "object", "example": { "aggressive": 0.12, "happy": 0.82, "party": 0.77, "relaxed": 0.31, "sad": 0.04 } }, "cached": { "type": "boolean", "title": "Cached", "description": "True if this result was served from the server-side cache. Cached responses are < 100 ms. The underlying analysis is identical to a fresh result.", "default": false } }, "type": "object", "required": [ "bpm", "bpm_confidence", "key", "key_confidence", "rms_energy" ], "title": "AudioAnalysisResponse" }, "Body_analyze_endpoint_analyze_post": { "properties": { "file": { "type": "string", "format": "binary", "title": "File", "description": "Audio file (MP3, WAV, OGG, FLAC, AAC/M4A)" } }, "type": "object", "required": [ "file" ], "title": "Body_analyze_endpoint_analyze_post" }, "Body_bulk_csv_endpoint_bulk_csv_post": { "properties": { "file": { "type": "string", "format": "binary", "title": "File", "description": "CSV file with `artist,title` columns." } }, "type": "object", "required": [ "file" ], "title": "Body_bulk_csv_endpoint_bulk_csv_post" }, "Body_identify_endpoint_identify_post": { "properties": { "file": { "type": "string", "format": "binary", "title": "File", "description": "Audio file (any format ffmpeg can decode, max 15 MB)" } }, "type": "object", "required": [ "file" ], "title": "Body_identify_endpoint_identify_post" }, "BpmSearchResponse": { "properties": { "bpm": { "type": "number", "title": "Bpm", "description": "Target BPM queried." }, "tolerance": { "type": "number", "title": "Tolerance", "description": "Tolerance window applied (±BPM)." }, "count": { "type": "integer", "title": "Count", "description": "Number of tracks returned." }, "tracks": { "items": { "$ref": "#/components/schemas/TrackLookupResponse" }, "type": "array", "title": "Tracks" } }, "type": "object", "required": [ "bpm", "tolerance", "count", "tracks" ], "title": "BpmSearchResponse" }, "BulkLookupItem": { "properties": { "track": { "type": "string", "maxLength": 200, "nullable": true, "title": "Track", "description": "Track name (partial match supported). Supply this OR `isrc` (or both — `isrc` is matched exactly first, the name is the fallback). `title` is also accepted as an alias. For short titles (≤2 chars, e.g. Aphex Twin '4'), supply `artist` to anchor the search.", "example": "Blinding Lights" }, "artist": { "title": "Artist", "description": "Artist name (optional, narrows the name search).", "nullable": true, "type": "string", "maxLength": 200, "example": "The Weeknd" }, "isrc": { "type": "string", "maxLength": 15, "nullable": true, "title": "Isrc", "description": "ISRC (e.g. `USUM71900001`, hyphens optional). Matched exactly first — resolves CJK / K-pop / niche tracks whose fuzzy name-match misses. Supply this OR `track`.", "example": "USUM71900001" } }, "type": "object", "title": "BulkLookupItem" }, "BulkLookupResponse": { "properties": { "results": { "items": { "$ref": "#/components/schemas/BulkTrackResult" }, "type": "array", "title": "Results" }, "found": { "type": "integer", "title": "Found", "description": "Number of tracks found in the catalog." }, "not_found": { "type": "integer", "title": "Not Found", "description": "Number of tracks not found." }, "requests_used": { "type": "integer", "title": "Requests Used", "description": "Number of quota requests consumed by this call." } }, "type": "object", "required": [ "results", "found", "not_found", "requests_used" ], "title": "BulkLookupResponse" }, "BulkTrackResult": { "properties": { "track": { "type": "string", "title": "Track", "description": "Track name as submitted (null for ISRC-only items).", "nullable": true }, "artist": { "title": "Artist", "description": "Artist name as submitted in the request.", "nullable": true, "type": "string" }, "isrc": { "type": "string", "nullable": true, "title": "Isrc", "description": "ISRC for this item, when one was supplied — echoed back so you can map results onto ISRC-keyed inputs." }, "found": { "type": "boolean", "title": "Found", "description": "True if the track was found in any source (catalog or fallback chain)." }, "result": { "description": "Audio features. Null if track not found.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TrackLookupResponse" } ] }, "backfill_status": { "title": "Backfill Status", "description": "`queued` when a field-backfill or on-demand ingest was started for this item; `processing` when the server time-box was hit before it resolved (retry to collect it); null otherwise.", "nullable": true, "type": "string" } }, "type": "object", "required": [ "found" ], "title": "BulkTrackResult" }, "CamelotCompatibleResponse": { "properties": { "input_camelot": { "type": "string", "title": "Input Camelot", "description": "Input Camelot notation as parsed.", "example": "8A" }, "input_key": { "type": "string", "title": "Input Key", "description": "Input as a human-readable key.", "example": "A-Minor" }, "compatible": { "items": { "$ref": "#/components/schemas/KeyVariant" }, "type": "array", "title": "Compatible", "description": "Keys that mix harmonically with the input. Always includes `same`, `relative`, `adjacent_up`, `adjacent_down`. With `extended=true` also includes `energy_boost` and `energy_drop`." } }, "type": "object", "required": [ "input_camelot", "input_key", "compatible" ], "title": "CamelotCompatibleResponse" }, "ChartEntry": { "properties": { "rank": { "type": "integer", "title": "Rank", "description": "Position on the chart, 1-indexed." }, "itunes_track_id": { "title": "Itunes Track Id", "description": "iTunes track id from the chart feed.", "nullable": true, "type": "string" }, "track_name": { "type": "string", "title": "Track Name" }, "artist_name": { "type": "string", "title": "Artist Name" }, "album_name": { "title": "Album Name", "nullable": true, "type": "string" }, "artwork_url": { "title": "Artwork Url", "description": "100×100 artwork from Apple, when available.", "nullable": true, "type": "string" }, "release_date": { "title": "Release Date", "nullable": true, "type": "string" }, "in_catalog": { "type": "boolean", "title": "In Catalog", "description": "True if this track is already analysed in the FreqBlog catalog (call /lookup or /track/{id}/embedding to retrieve features)." }, "catalog_track": { "description": "Catalog row when `in_catalog=true`, including any populated `mbid`, `isrc`, `genre`.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TrackStub" } ] } }, "type": "object", "required": [ "rank", "track_name", "artist_name", "in_catalog" ], "title": "ChartEntry" }, "ChartResponse": { "properties": { "country": { "type": "string", "title": "Country", "description": "ISO 3166-1 alpha-2 country code as queried.", "example": "gb" }, "type": { "type": "string", "title": "Type", "description": "Chart type. Currently `most-played` (Apple's daily top songs)." }, "fetched_at": { "type": "string", "title": "Fetched At", "description": "ISO 8601 timestamp this chart snapshot was fetched. Cached for 12 hours." }, "count": { "type": "integer", "title": "Count" }, "entries": { "items": { "$ref": "#/components/schemas/ChartEntry" }, "type": "array", "title": "Entries" } }, "type": "object", "required": [ "country", "type", "fetched_at", "count", "entries" ], "title": "ChartResponse" }, "EmbeddingResponse": { "properties": { "itunes_track_id": { "type": "string", "title": "Itunes Track Id", "example": "1488408568" }, "track_name": { "type": "string", "title": "Track Name", "example": "Blinding Lights" }, "artist_name": { "type": "string", "title": "Artist Name", "example": "The Weeknd" }, "dim": { "type": "integer", "title": "Dim", "description": "Length of the embedding vector.", "example": 18 }, "fields": { "items": { "type": "string" }, "type": "array", "title": "Fields", "description": "Field name for each position in `embedding`. Always returned in a stable order so callers can rely on positional indexing." }, "embedding": { "items": { "type": "number" }, "type": "array", "title": "Embedding", "description": "Numeric feature vector. Missing values are filled with sensible defaults (see `embedding_mask`)." }, "embedding_mask": { "items": { "type": "boolean" }, "type": "array", "title": "Embedding Mask", "description": "Per-position truthy when the value came from real analysis, falsy when filled with a default. Use to mask out filler values in similarity calculations." } }, "type": "object", "required": [ "itunes_track_id", "track_name", "artist_name", "dim", "fields", "embedding", "embedding_mask" ], "title": "EmbeddingResponse", "description": "Numeric feature vector for a track — convenient for ML / similarity / clustering." }, "ErrorResponse": { "properties": { "detail": { "type": "string", "title": "Detail" }, "error_code": { "title": "Error Code", "nullable": true, "type": "string" } }, "type": "object", "required": [ "detail" ], "title": "ErrorResponse" }, "ExtendedAudioFeatures": { "properties": { "gender": { "title": "Gender", "description": "Vocal gender classification: `male` / `female`. Inferred from MFCC + F0 features. Best for tracks with sustained vocals; less reliable on instrumentals or short clips.", "nullable": true, "type": "string", "example": "female" }, "timbre": { "title": "Timbre", "description": "Timbral brightness classification: `bright` / `dark`. Bright = strong high-frequency content (cymbals, electric guitar); dark = bass-dominant.", "nullable": true, "type": "string", "example": "bright" }, "tonal_atonal": { "title": "Tonal Atonal", "description": "Tonality classification: `tonal` / `atonal`. Tonal = clear key centre; atonal = ambiguous or shifting tonality (typical of avant-garde / drone).", "nullable": true, "type": "string", "example": "tonal" } }, "type": "object", "title": "ExtendedAudioFeatures", "description": "Higher-level categorical labels from AcousticBrainz. Each value is the\nmost-confident class from a binary classifier — useful for filtering /\nbucketing but not for fine-grained analysis." }, "FreeKeyRequest": { "properties": { "email": { "type": "string", "title": "Email" }, "name": { "type": "string", "title": "Name", "default": "" }, "turnstile_token": { "type": "string", "title": "Turnstile Token", "default": "" }, "utm_source": { "type": "string", "title": "Utm Source", "default": "" }, "utm_medium": { "type": "string", "title": "Utm Medium", "default": "" }, "utm_campaign": { "type": "string", "title": "Utm Campaign", "default": "" } }, "type": "object", "required": [ "email" ], "title": "FreeKeyRequest" }, "GenreInfo": { "properties": { "genre": { "type": "string", "title": "Genre", "example": "electronic" }, "track_count": { "type": "integer", "title": "Track Count", "description": "Number of catalog tracks tagged with this genre." } }, "type": "object", "required": [ "genre", "track_count" ], "title": "GenreInfo" }, "GenreTracksResponse": { "properties": { "genre": { "type": "string", "title": "Genre" }, "total": { "type": "integer", "title": "Total", "description": "Total tracks in catalog for this genre (independent of `limit`/`offset`)." }, "count": { "type": "integer", "title": "Count" }, "tracks": { "items": { "$ref": "#/components/schemas/TrackStub" }, "type": "array", "title": "Tracks" } }, "type": "object", "required": [ "genre", "total", "count", "tracks" ], "title": "GenreTracksResponse" }, "GenresResponse": { "properties": { "count": { "type": "integer", "title": "Count", "description": "Number of distinct genres returned." }, "genres": { "items": { "$ref": "#/components/schemas/GenreInfo" }, "type": "array", "title": "Genres", "description": "Genres ordered by track_count descending." } }, "type": "object", "required": [ "count", "genres" ], "title": "GenresResponse" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "IdentifyResponse": { "properties": { "matched": { "type": "boolean", "title": "Matched", "description": "True when the fingerprint matched a known recording in the AcoustID database." }, "score": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Score", "description": "AcoustID match confidence, 0–1.", "example": 0.94 }, "acoustid": { "title": "Acoustid", "description": "AcoustID UUID for the recording group, when known.", "nullable": true, "type": "string" }, "mbid": { "title": "Mbid", "description": "MusicBrainz Recording ID for the matched recording.", "nullable": true, "type": "string" }, "isrc": { "title": "Isrc", "description": "ISRC, when resolvable from the matched recording.", "nullable": true, "type": "string" }, "track_name": { "title": "Track Name", "description": "Track title from the AcoustID/MusicBrainz match.", "nullable": true, "type": "string" }, "artist_name": { "title": "Artist Name", "description": "Artist name(s) from the AcoustID/MusicBrainz match.", "nullable": true, "type": "string" }, "in_catalog": { "type": "boolean", "title": "In Catalog", "description": "True if the matched recording is already in the FreqBlog catalog. When true, `audio_features` is populated.", "default": false }, "audio_features": { "description": "Full FreqBlog audio features for the matched recording — populated when the MBID resolves to a catalog row, otherwise null. Call `/lookup` separately if you want to trigger an on-demand analysis for unknown recordings.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TrackLookupResponse" } ] }, "fingerprint_duration_seconds": { "title": "Fingerprint Duration Seconds", "description": "Duration of the fingerprinted audio (seconds), as reported by Chromaprint.", "nullable": true, "type": "number" } }, "type": "object", "required": [ "matched", "score" ], "title": "IdentifyResponse" }, "KeySearchResponse": { "properties": { "key": { "type": "string", "title": "Key", "description": "Resolved key in stored format, e.g. 'A-Minor'." }, "camelot": { "title": "Camelot", "description": "Camelot notation for this key.", "nullable": true, "type": "string" }, "open_key": { "title": "Open Key", "description": "Open Key notation for this key.", "nullable": true, "type": "string" }, "count": { "type": "integer", "title": "Count", "description": "Number of tracks returned." }, "tracks": { "items": { "$ref": "#/components/schemas/TrackLookupResponse" }, "type": "array", "title": "Tracks" } }, "type": "object", "required": [ "key", "count", "tracks" ], "title": "KeySearchResponse" }, "KeyVariant": { "properties": { "camelot": { "type": "string", "title": "Camelot", "description": "Camelot notation, e.g. `8A`.", "example": "8A" }, "open_key": { "title": "Open Key", "description": "Open Key notation, e.g. `1m`.", "nullable": true, "type": "string", "example": "1m" }, "key": { "type": "string", "title": "Key", "description": "Human-readable key, e.g. `A-Minor`.", "example": "A-Minor" }, "relation": { "type": "string", "title": "Relation", "description": "How this key relates to the input. One of: `same` (same key), `relative` (same number, opposite letter — minor↔major), `adjacent_up` (one step clockwise on the wheel), `adjacent_down` (one step counterclockwise), `energy_boost` (+7 same letter — common DJ key change up), `energy_drop` (-7 same letter — key change down).", "example": "adjacent_up" } }, "type": "object", "required": [ "camelot", "key", "relation" ], "title": "KeyVariant", "description": "One harmonically compatible key, returned by `/key/{camelot}/compatible`." }, "RadioResponse": { "properties": { "seed": { "$ref": "#/components/schemas/TrackStub" }, "count": { "type": "integer", "title": "Count" }, "constraints": { "type": "object", "title": "Constraints", "description": "Constraints applied to the walk: target BPM range, key adjacency depth, min similarity score." }, "tracks": { "items": { "$ref": "#/components/schemas/TrackStub" }, "type": "array", "title": "Tracks", "description": "Playlist in play order. Index 0 = seed, last index = closing track." } }, "type": "object", "required": [ "seed", "count", "constraints", "tracks" ], "title": "RadioResponse" }, "TransitionComponents": { "properties": { "harmonic": { "type": "integer", "maximum": 100, "minimum": 0, "title": "Harmonic", "description": "Key compatibility (Camelot wheel relationship), 0-100.", "example": 90 }, "tempo": { "type": "integer", "maximum": 100, "minimum": 0, "title": "Tempo", "description": "BPM compatibility — octave-aware (half/double time counts as a match), 0-100.", "example": 95 }, "energy": { "type": "integer", "maximum": 100, "minimum": 0, "title": "Energy", "description": "Smoothness of the energy step between the two tracks, 0-100.", "example": 88 } }, "type": "object", "required": [ "harmonic", "tempo", "energy" ], "title": "TransitionComponents", "description": "The three 0-100 sub-scores behind an overall mix score." }, "TransitionDetail": { "properties": { "key_relation": { "type": "string", "title": "Key Relation", "description": "How the two keys relate on the Camelot wheel: `same`, `relative` (minor↔major, same root), `adjacent_up`/`adjacent_down` (±1 hop), `energy_boost`/`energy_drop` (±7 — a deliberate lift/drop), `incompatible` (a clash), or `unknown` (one track has no detected key).", "example": "adjacent_up" }, "from_camelot": { "title": "From Camelot", "nullable": true, "type": "string", "example": "8A" }, "to_camelot": { "title": "To Camelot", "nullable": true, "type": "string", "example": "9A" }, "from_bpm": { "title": "From Bpm", "nullable": true, "type": "number", "example": 126.0 }, "to_bpm": { "title": "To Bpm", "nullable": true, "type": "number", "example": 128.0 }, "bpm_delta": { "type": "number", "title": "Bpm Delta", "description": "Signed BPM difference (to − from) after octave matching.", "example": 2.0 }, "bpm_octave_matched": { "type": "boolean", "title": "Bpm Octave Matched", "description": "True if the destination was matched at half/double time (e.g. 70 BPM treated as 140 to beat-match)." }, "from_energy": { "title": "From Energy", "description": "Source energy, normalised [0,1].", "nullable": true, "type": "number", "example": 0.62 }, "to_energy": { "title": "To Energy", "description": "Destination energy, normalised [0,1].", "nullable": true, "type": "number", "example": 0.66 }, "energy_delta": { "type": "number", "title": "Energy Delta", "description": "Signed energy difference (to − from), [-1,1].", "example": 0.04 } }, "type": "object", "required": [ "key_relation", "bpm_delta", "bpm_octave_matched", "energy_delta" ], "title": "TransitionDetail", "description": "The raw values the score was computed from — surface them to build your own UI." }, "TransitionResponse": { "properties": { "from_track": { "allOf": [ { "$ref": "#/components/schemas/TrackStub" } ], "description": "The track you're mixing OUT of." }, "to_track": { "allOf": [ { "$ref": "#/components/schemas/TrackStub" } ], "description": "The track you're mixing INTO." }, "score": { "type": "integer", "maximum": 100, "minimum": 0, "title": "Score", "description": "Overall 0-100 mix compatibility (0.50·harmonic + 0.30·tempo + 0.20·energy).", "example": 92 }, "components": { "$ref": "#/components/schemas/TransitionComponents" }, "detail": { "$ref": "#/components/schemas/TransitionDetail" }, "reason": { "type": "string", "title": "Reason", "description": "Plain-English explanation of the score.", "example": "8A->9A +1 adjacent, 126->128 BPM (+2.0), energy +0.04" } }, "type": "object", "required": [ "from_track", "to_track", "score", "components", "detail", "reason" ], "title": "TransitionResponse", "description": "Pairwise mix-compatibility score between two catalog tracks." }, "NextTrackSuggestion": { "properties": { "track": { "$ref": "#/components/schemas/TrackStub" }, "score": { "type": "integer", "maximum": 100, "minimum": 0, "title": "Score", "description": "Overall mix-compatibility score from the seed into this track.", "example": 96 }, "components": { "$ref": "#/components/schemas/TransitionComponents" }, "reason": { "type": "string", "title": "Reason", "description": "Plain-English explanation of the score.", "example": "11B->11B same key, 118->117 BPM (-0.29), energy +0.12" } }, "type": "object", "required": [ "track", "score", "components", "reason" ], "title": "NextTrackSuggestion" }, "NextTrackResponse": { "properties": { "seed": { "allOf": [ { "$ref": "#/components/schemas/TrackStub" } ], "description": "The track you're mixing out of." }, "count": { "type": "integer", "title": "Count", "description": "Number of suggestions returned (≤ `n`)." }, "suggestions": { "items": { "$ref": "#/components/schemas/NextTrackSuggestion" }, "type": "array", "title": "Suggestions", "description": "Best-first by overall mix-compatibility score." } }, "type": "object", "required": [ "seed", "count", "suggestions" ], "title": "NextTrackResponse", "description": "Ranked next-track suggestions for a seed — the candidates that mix best." }, "SetlistRequest": { "properties": { "track_ids": { "items": { "type": "string" }, "type": "array", "maxItems": 100, "minItems": 2, "title": "Track Ids", "description": "Catalog `itunes_track_id`s to order. 2-100. Duplicates are collapsed." }, "arc": { "type": "string", "enum": [ "peak_time", "warmup", "cooldown", "flat" ], "default": "peak_time", "title": "Arc", "description": "Target energy shape: `peak_time` (build to a peak ~3/4 in, then ease), `warmup` (steady rise), `cooldown` (steady fall), `flat` (hold — order purely for smooth transitions)." }, "start_track_id": { "title": "Start Track Id", "description": "Optional fixed opener (must be one of `track_ids`); otherwise chosen to fit the arc.", "nullable": true, "type": "string" } }, "type": "object", "required": [ "track_ids" ], "title": "SetlistRequest", "description": "Order a crate of tracks into a beat-matched, energy-arced set." }, "SetlistStep": { "properties": { "from_index": { "type": "integer", "title": "From Index", "description": "Index in `tracks` of the outgoing track." }, "to_index": { "type": "integer", "title": "To Index", "description": "Index in `tracks` of the incoming track." }, "score": { "type": "integer", "maximum": 100, "minimum": 0, "title": "Score", "description": "Transition score for this step." }, "reason": { "type": "string", "title": "Reason", "description": "Plain-English explanation of this step's transition." } }, "type": "object", "required": [ "from_index", "to_index", "score", "reason" ], "title": "SetlistStep" }, "SetlistResponse": { "properties": { "arc": { "type": "string", "title": "Arc", "description": "The arc shape that was applied.", "example": "peak_time" }, "count": { "type": "integer", "title": "Count", "description": "Number of tracks placed in the set." }, "flow_score": { "type": "integer", "maximum": 100, "minimum": 0, "title": "Flow Score", "description": "Mean transition score across the whole set — how smoothly it mixes.", "example": 91 }, "tracks": { "items": { "$ref": "#/components/schemas/TrackStub" }, "type": "array", "title": "Tracks", "description": "Tracks in play order. Index 0 = opener." }, "transitions": { "items": { "$ref": "#/components/schemas/SetlistStep" }, "type": "array", "title": "Transitions", "description": "Per-step transition scores, one per consecutive pair." }, "omitted": { "items": { "type": "string" }, "type": "array", "title": "Omitted", "description": "Requested ids not found in the catalog (skipped)." } }, "type": "object", "required": [ "arc", "count", "flow_score", "tracks", "transitions", "omitted" ], "title": "SetlistResponse", "description": "A crate ordered into a continuous, beat-matched, energy-arced set." }, "SearchResponse": { "properties": { "q": { "type": "string", "title": "Q", "description": "The query string as submitted." }, "count": { "type": "integer", "title": "Count", "description": "Number of tracks returned (≤ `limit`)." }, "results": { "items": { "$ref": "#/components/schemas/TrackStub" }, "type": "array", "title": "Results", "description": "Track stubs ordered by full-text relevance, then popularity descending." } }, "type": "object", "required": [ "q", "count", "results" ], "title": "SearchResponse" }, "SimilarResponse": { "properties": { "seed": { "$ref": "#/components/schemas/TrackStub", "description": "The seed track the recommendations are based on." }, "count": { "type": "integer", "title": "Count", "description": "Number of similar tracks returned (≤ `limit`)." }, "results": { "items": { "$ref": "#/components/schemas/SimilarTrackResult" }, "type": "array", "title": "Results", "description": "Tracks ordered by descending cosine similarity to the seed." } }, "type": "object", "required": [ "seed", "count", "results" ], "title": "SimilarResponse" }, "SimilarTrackResult": { "properties": { "track": { "$ref": "#/components/schemas/TrackStub" }, "score": { "type": "number", "title": "Score", "description": "Cosine similarity in [-1, 1]. Typically [0, 1] in practice. 1.0 = effectively identical features; 0.0 = orthogonal; negative = anti-correlated.", "example": 0.94 } }, "type": "object", "required": [ "track", "score" ], "title": "SimilarTrackResult" }, "TrackLookupResponse": { "properties": { "track_name": { "type": "string", "title": "Track Name", "description": "Track name as indexed from Apple Music charts or MusicBrainz.", "example": "Blinding Lights" }, "artist_name": { "type": "string", "title": "Artist Name", "description": "Artist name.", "example": "The Weeknd" }, "album_name": { "title": "Album Name", "description": "Album or single title. Populated for catalog tracks (Apple Music / iTunes source).", "nullable": true, "type": "string", "example": "After Hours" }, "itunes_track_id": { "type": "string", "title": "Itunes Track Id", "description": "iTunes track ID for catalog tracks; 'mb:{mbid}' for AcousticBrainz-sourced tracks; 'fma:{hash}' for FMA-sourced tracks; 'msd:{hash}' for Million Song Dataset tracks.", "example": "1488408568" }, "isrc": { "title": "Isrc", "description": "International Standard Recording Code. Uniquely identifies this specific master recording.", "nullable": true, "type": "string", "example": "GBAYE0601498" }, "mbid": { "title": "Mbid", "description": "MusicBrainz Recording ID (UUID). Cross-reference to the open music encyclopedia.", "nullable": true, "type": "string", "example": "5b11f4ce-a62d-471e-81fc-a69a8278c7da" }, "is_remix": { "title": "Is Remix", "description": "True when this recording is a third-party remix/bootleg (parsed from the title). False for originals and same-performance versions. `/lookup` only.", "type": "boolean", "example": true }, "remixer": { "title": "Remixer", "description": "The third-party artist credited with the remix, when attributable; null otherwise. `/lookup` only.", "nullable": true, "type": "string", "example": "Alesso" }, "mix_name": { "title": "Mix Name", "description": "Version/mix descriptor from the title (e.g. 'Extended Mix', 'Alesso Remix'). Null for a plain original. `/lookup` only.", "nullable": true, "type": "string", "example": "Extended Mix" }, "remix_of_isrc": { "title": "Remix Of Isrc", "description": "ISRC of the ORIGINAL recording this remix is based on, when the original is in the catalog. Lets you jump from a remix to its source. Null otherwise. `/lookup` only.", "nullable": true, "type": "string", "example": "USUM71116097" }, "release_date": { "title": "Release Date", "description": "Release date in ISO 8601 format (YYYY-MM-DD). Sourced from iTunes. Null for fallback-layer tracks.", "nullable": true, "type": "string", "example": "2020-03-20" }, "duration_ms": { "title": "Duration Ms", "description": "Full track duration in milliseconds from the iTunes catalog. Distinct from `duration_seconds` (which is the analysed 30s window).", "nullable": true, "type": "integer", "example": 200040 }, "explicit": { "title": "Explicit", "description": "True if the track is marked explicit by the source. Null when not reported.", "nullable": true, "type": "boolean", "example": false }, "source": { "title": "Source", "description": "Ingest source that first added this track, e.g. `apple_chart`, `deezer_chart`, `itunes_search`, `lastfm`, `jamendo`, `discovery_graph`.", "nullable": true, "type": "string", "example": "apple_chart" }, "first_ingested_at": { "title": "First Ingested At", "description": "ISO 8601 UTC timestamp of when this track was first added to the catalog.", "nullable": true, "type": "string", "example": "2025-11-14T01:23:45" }, "bpm": { "type": "number", "maximum": 300.0, "minimum": 20.0, "title": "Bpm", "description": "Tempo in beats per minute.", "example": 171.0 }, "bpm_alt": { "title": "Bpm Alt", "description": "Half-time/double-time corrected alternative BPM, when our heuristic suggests Essentia locked onto the wrong beat grid. Null when no correction is warranted. **Never** replaces `bpm` — use this when your downstream tooling expects the perceived rather than detected tempo (e.g. pop tracks like 'Blinding Lights' where Essentia returns ~85 but the perceived BPM is ~171).", "nullable": true, "type": "number", "example": 170.78 }, "bpm_confidence": { "title": "Bpm Confidence", "description": "Beat-strength score from Essentia RhythmExtractor2013. Null for AcousticBrainz-sourced tracks.", "nullable": true, "type": "number", "example": 3.8 }, "key": { "type": "string", "title": "Key", "description": "Musical key and scale, e.g. `C#-Minor`.", "example": "C#-Minor" }, "key_confidence": { "title": "Key Confidence", "description": "Key detection confidence [0–1]. Null for AcousticBrainz-sourced tracks.", "nullable": true, "type": "number", "maximum": 1.0, "minimum": 0.0, "example": 0.76 }, "mode": { "title": "Mode", "description": "Spotify-compatible mode integer: 0 = minor, 1 = major.", "nullable": true, "type": "integer", "maximum": 1.0, "minimum": 0.0, "example": 0 }, "key_int": { "title": "Key Int", "description": "Spotify-compatible pitch-class integer for the key: 0 = C, 1 = C♯/D♭, 2 = D, … 11 = B. `null` when the key is undetected/atonal (the Spotify-shaped `/v1/audio-features/{id}` endpoint reports `-1` in that case, matching Spotify's convention).", "nullable": true, "type": "integer", "maximum": 11.0, "minimum": 0.0, "example": 1 }, "camelot": { "title": "Camelot", "description": "Camelot wheel notation, e.g. `12A`.", "nullable": true, "type": "string", "example": "12A" }, "open_key": { "title": "Open Key", "description": "Open Key notation, e.g. `5m` (C#-Minor). d=major, m=minor.", "nullable": true, "type": "string", "example": "5m" }, "energy": { "title": "Energy", "description": "Normalised RMS energy [0–1]. Equivalent to Spotify's `energy` field.", "nullable": true, "type": "number", "maximum": 1.0, "minimum": 0.0, "example": 0.91 }, "loudness_db": { "title": "Loudness Db", "description": "Integrated loudness in dBFS.", "nullable": true, "type": "number", "example": -7.4 }, "danceability": { "title": "Danceability", "description": "Danceability score [0–1].", "nullable": true, "type": "number", "maximum": 1.0, "minimum": 0.0, "example": 0.78 }, "valence": { "title": "Valence", "description": "Musical positiveness [0–1].", "nullable": true, "type": "number", "maximum": 1.0, "minimum": 0.0, "example": 0.54 }, "speechiness": { "title": "Speechiness", "description": "Spoken word presence [0–1].", "nullable": true, "type": "number", "maximum": 1.0, "minimum": 0.0, "example": 0.06 }, "instrumentalness": { "title": "Instrumentalness", "description": "Instrumental likelihood [0–1].", "nullable": true, "type": "number", "maximum": 1.0, "minimum": 0.0, "example": 0.04 }, "liveness": { "title": "Liveness", "description": "Live performance likelihood [0–1].", "nullable": true, "type": "number", "maximum": 1.0, "minimum": 0.0, "example": 0.09 }, "acousticness": { "title": "Acousticness", "description": "Acoustic confidence [0–1].", "nullable": true, "type": "number", "maximum": 1.0, "minimum": 0.0, "example": 0.21 }, "time_signature": { "title": "Time Signature", "description": "Estimated time signature (3, 4, 5, etc.).", "nullable": true, "type": "integer", "example": 4 }, "mood": { "title": "Mood", "description": "MIREX-style mood category: happy, calm, sad, tense, energetic, melancholic, or neutral.", "nullable": true, "type": "string", "example": "happy" }, "mood_vector": { "title": "Mood Vector", "description": "Dimensional mood scores [0–1] across five axes: `happy`, `sad`, `aggressive`, `relaxed`, `party`. Populated when an AcousticBrainz high-level match is found; `null` otherwise.", "nullable": true, "additionalProperties": { "type": "number" }, "type": "object", "example": { "aggressive": 0.12, "happy": 0.82, "party": 0.77, "relaxed": 0.31, "sad": 0.04 } }, "representative_segment_start": { "title": "Representative Segment Start", "description": "Start time (seconds) of the highest-energy 30s window. 0.0 for 30s previews.", "nullable": true, "type": "number", "example": 0.0 }, "onset_rate": { "title": "Onset Rate", "description": "Onset events per second from AcousticBrainz low-level analysis. Higher values indicate more rhythmic or percussive content. Populated when an AcousticBrainz match is found; `null` otherwise.", "nullable": true, "type": "number", "example": 2.86 }, "dynamic_complexity": { "title": "Dynamic Complexity", "description": "Loudness variation over the track (dB), from AcousticBrainz low-level analysis. Higher values mean wider dynamic range; lower values mean more compressed mastering. Populated when an AcousticBrainz match is found; `null` otherwise.", "nullable": true, "type": "number", "example": 5.61 }, "tuning_frequency": { "title": "Tuning Frequency", "description": "Estimated A4 reference frequency in Hz, from AcousticBrainz tonal analysis. Modern recordings cluster near 440 Hz; older or non-Western recordings may diverge. Populated when an AcousticBrainz match is found; `null` otherwise.", "nullable": true, "type": "number", "example": 440.0 }, "average_loudness": { "title": "Average Loudness", "description": "Average loudness as a normalised value [0–1] from AcousticBrainz low-level analysis. Distinct from `loudness_db` (which is dBFS from this service's own analysis). Populated when an AcousticBrainz match is found; `null` otherwise.", "nullable": true, "type": "number", "example": 0.703 }, "genre": { "title": "Genre", "description": "Broad genre classification (e.g. electronic, rock, pop, hip-hop, jazz). Sourced from AcousticBrainz or Last.fm.", "nullable": true, "type": "string", "example": "electronic" }, "extended": { "description": "Higher-level AcousticBrainz classifications. Populated when the track has an AcousticBrainz match — null otherwise. **Not counted toward the 38-field headline** because each value is a categorical label, not an analysis field.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ExtendedAudioFeatures" } ] }, "feature_source": { "title": "Feature Source", "description": "Provenance of the audio feature data. One of: `essentia_preview` (analysed from a 30s preview by this service), `acousticbrainz` (matched by MBID against the AcousticBrainz dump), `fma` (FMA Echo Nest dataset), `msd` (Million Song Dataset), `user_upload` (analysed from a file the user uploaded).", "nullable": true, "type": "string", "example": "essentia_preview" }, "backfill_status": { "title": "Backfill Status", "description": "Backfill job status if one was queued: 'queued', 'processing', 'completed', 'failed'. Null if no backfill was needed.", "nullable": true, "type": "string", "example": "queued" }, "backfill_notification_id": { "title": "Backfill Notification Id", "description": "Notification ID for tracking backfill progress. Use to query backfill_notifications table.", "nullable": true, "type": "string", "example": "backfill_1488408568_1713950025" } }, "type": "object", "required": [ "track_name", "artist_name", "itunes_track_id", "bpm", "key" ], "title": "TrackLookupResponse" }, "TrackStub": { "properties": { "itunes_track_id": { "type": "string", "title": "Itunes Track Id", "description": "Track id (catalog `itunes_track_id` or synthetic prefix). Pass to `/track/{id}/embedding` or use the name+artist with `/lookup`.", "example": "1488408568" }, "track_name": { "type": "string", "title": "Track Name", "example": "Blinding Lights" }, "artist_name": { "type": "string", "title": "Artist Name", "example": "The Weeknd" }, "album_name": { "title": "Album Name", "nullable": true, "type": "string", "example": "After Hours" }, "popularity": { "type": "integer", "title": "Popularity", "description": "Internal popularity score (higher = more popular). Used for default ordering.", "default": 0 }, "mbid": { "title": "Mbid", "description": "MusicBrainz Recording ID, when known.", "nullable": true, "type": "string" }, "isrc": { "title": "Isrc", "description": "ISRC, when known.", "nullable": true, "type": "string" }, "genre": { "title": "Genre", "description": "Broad genre classification, when known.", "nullable": true, "type": "string" }, "release_date": { "title": "Release Date", "description": "ISO 8601 release date, when known.", "nullable": true, "type": "string", "example": "2019-11-29" }, "duration_ms": { "title": "Duration Ms", "nullable": true, "type": "integer", "example": 200040 }, "explicit": { "title": "Explicit", "nullable": true, "type": "boolean" }, "source": { "title": "Source", "description": "Ingest source identifier, e.g. `apple_chart`, `itunes_search`, `lastfm`.", "nullable": true, "type": "string" } }, "type": "object", "required": [ "itunes_track_id", "track_name", "artist_name" ], "title": "TrackStub", "description": "Minimal track shape for search and browse endpoints. No audio features.\nUse `/lookup` for full audio features once you have a track id." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "WebhookConfig": { "properties": { "url": { "type": "string", "maxLength": 500, "minLength": 8, "title": "Url", "description": "HTTPS URL where backfill notifications will be POSTed.", "example": "https://example.com/freqblog-webhook" } }, "type": "object", "required": [ "url" ], "title": "WebhookConfig" }, "WebhookStatus": { "properties": { "url": { "title": "Url", "description": "Current webhook URL, or null if none configured.", "nullable": true, "type": "string" }, "signing_note": { "type": "string", "title": "Signing Note", "description": "How to verify webhook authenticity.", "default": "Each POST is signed with X-FreqBlog-Signature: sha256=<hex>, computed as HMAC-SHA256(sha256(your_api_key_plaintext), request_body). Verify on your end to confirm the request came from FreqBlog." } }, "type": "object", "title": "WebhookStatus" }, "RecommendationSeed": { "properties": { "id": { "type": "string", "title": "Id", "description": "Seed track id as supplied.", "example": "apple_ad1829eeccb70f9a" }, "found": { "type": "boolean", "title": "Found", "description": "True if the seed was usable (in the catalog with enough audio features)." } }, "type": "object", "required": [ "id", "found" ], "title": "RecommendationSeed" }, "RecommendationsResponse": { "properties": { "seeds": { "items": { "$ref": "#/components/schemas/RecommendationSeed" }, "type": "array", "title": "Seeds", "description": "Echo of the supplied seeds with a found/unfound flag." }, "seed_query": { "description": "When seeded by name (`track`/`artist`) instead of an id, the catalogue track that name resolved to — so you can confirm the right track was picked. Null when seeding by `seed_tracks`.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TrackStub" } ], "title": "Seed Query" }, "count": { "type": "integer", "title": "Count", "description": "Number of recommended tracks returned (≤ `limit`)." }, "tracks": { "items": { "$ref": "#/components/schemas/SimilarTrackResult" }, "type": "array", "title": "Tracks", "description": "Recommended tracks ordered by genre-aware relevance to the seed blend. `score` is the raw audio-feature cosine similarity (genre affinity influences ordering, not the score), so it may not be strictly descending." } }, "type": "object", "required": [ "seeds", "count", "tracks" ], "title": "RecommendationsResponse", "description": "Spotify-shaped recommendations: blend up to 5 seed tracks and return the nearest catalogue tracks by audio-feature similarity, re-ranked by genre affinity. Drop-in for the removed Spotify GET /v1/recommendations — FreqBlog catalog ids, open-data ranking." }, "RelatedArtist": { "properties": { "artist_name": { "type": "string", "title": "Artist Name", "example": "AC/DC" }, "score": { "type": "number", "title": "Score", "description": "Aggregate similarity of this artist's tracks to the seed artist (higher = closer).", "example": 0.93 }, "match_count": { "type": "integer", "title": "Match Count", "description": "How many of this artist's tracks fell in the seed artist's neighbourhood." }, "sample_track_id": { "title": "Sample Track Id", "description": "A representative catalog track id by this artist — pass to `/lookup` or `/next-track`.", "nullable": true, "type": "string", "example": "apple_ad1829eeccb70f9a" } }, "type": "object", "required": [ "artist_name", "score", "match_count" ], "title": "RelatedArtist" }, "RelatedArtistsResponse": { "properties": { "artist": { "type": "string", "title": "Artist", "description": "The seed artist as supplied.", "example": "Van Halen" }, "count": { "type": "integer", "title": "Count", "description": "Number of related artists returned (≤ `limit`)." }, "related": { "items": { "$ref": "#/components/schemas/RelatedArtist" }, "type": "array", "title": "Related", "description": "Related artists, best-first." } }, "type": "object", "required": [ "artist", "count", "related" ], "title": "RelatedArtistsResponse", "description": "Spotify-shaped related-artists: artists who make tracks similar to the seed artist's. Drop-in for the removed Spotify /v1/artists/{id}/related-artists." }, "TagItem": { "type": "object", "title": "TagItem", "required": [ "tag", "category", "confidence", "provenance" ], "properties": { "tag": { "type": "string", "title": "Tag", "description": "Human-readable tag, e.g. `high-energy`, `acoustic`, `party`, `synthwave`.", "example": "high-energy" }, "category": { "type": "string", "title": "Category", "description": "energy | danceability | valence | acousticness | instrumentalness | mood | genre.", "example": "energy" }, "value": { "type": "number", "nullable": true, "title": "Value", "description": "Underlying [0,1] score for numeric tags; null for label-only tags (mood category, genre).", "example": 0.91 }, "confidence": { "type": "string", "title": "Confidence", "description": "measured | derived | model-estimated | catalog-genre.", "example": "measured" }, "provenance": { "type": "string", "title": "Provenance", "description": "essentia | valence+energy | acousticbrainz | catalog.", "example": "essentia" } } }, "TagResponse": { "type": "object", "title": "TagResponse", "required": [ "track", "count", "tags", "disclaimer" ], "properties": { "track": { "$ref": "#/components/schemas/TrackStub" }, "count": { "type": "integer", "title": "Count", "description": "Number of tags returned." }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/TagItem" }, "title": "Tags", "description": "Tags, each with a confidence + provenance so you can judge reliability." }, "disclaimer": { "type": "string", "title": "Disclaimer", "description": "How to read the confidence levels." } } } } }, "tags": [ { "name": "Catalog" }, { "name": "Spotify-compat" } ] } </article></body></html>

{ "openapi": "3.0.3", "info": { "title": "Music Metadata API", "description": "\n## The Spotify `audio-features` replacement\n\nSpotify deprecated their `audio-features` endpoint on **27 November 2024**.\nThis API fills that gap — upload any audio file, get BPM, key, and energy back in seconds.\n\n---\n\n### Authentication\n\nPass your API key in the `X-Api-Key` header:\n\n```\nX-Api-Key: sk_live_your_key_here\n```\n\nNo key configured on the server = open access (development mode).\n\n---\n\n### Spotify Migration Guide\n\n| Spotify field | This API | Notes |\n|---|---|---|\n| `tempo` | `bpm` | Same unit (BPM). Add `bpm_confidence` to filter weak beats. |\n| `energy` | `energy` | Both normalised [0-1]. Different algorithm. |\n| `key` + `mode` | `key`, `mode`, `camelot`, `open_key` | Human-readable key + numeric mode + Camelot + Open Key notation. |\n| `loudness` | `loudness_db` | Both in dBFS. Direct equivalent. |\n| `time_signature` | `time_signature` | Identical field. Most tracks return 4. |\n| `duration_ms` | `duration_ms` | Full track length from iTunes (catalog tracks only). |\n| `danceability` | `danceability` | Signal-analysis approximation [0–1]. |\n| `valence` | `valence` | Signal-analysis approximation [0–1]. |\n| `acousticness` | `acousticness` | Spectral flatness based [0–1]. |\n| `instrumentalness` | `instrumentalness` | MFCC vocal-formant based [0–1]. |\n| `liveness` | `liveness` | Noise floor ratio proxy [0–1]. |\n| `speechiness` | `speechiness` | Zero-crossing rate based [0–1]. |\n\n### Extra fields (not in Spotify)\n\n| Field | Notes |\n|---|---|\n| `bpm_confidence` | Beat-strength score — filter low-rhythm/ambient tracks. |\n| `key_confidence` | Key detection reliability [0–1]. Below 0.4 = atonal. |\n| `camelot` | Camelot wheel notation for DJs (e.g. `8A`, `3B`). |\n| `open_key` | Open Key notation for Serato / Mixed In Key users (e.g. `1m`, `4d`). |\n| `mood` | MIREX-style mood category derived from valence + energy. Values: happy, calm, sad, tense, energetic, melancholic, neutral. |\n| `mood_vector` | Dimensional mood scores [0–1] across 5 axes (`happy`, `sad`, `aggressive`, `relaxed`, `party`). Sourced from public music classifiers. |\n| `representative_segment_start` | Start time (seconds) of the highest-energy 30-second window — the chorus or drop. Useful for sync licensing and preview generation. |\n| `genre` | Broad genre classification (e.g. electronic, rock, pop, hip-hop). Sourced from public music databases. |\n| `album_name` | Album or single title from catalog data. `/lookup` only. |\n| `release_date` | ISO 8601 release date (YYYY-MM-DD) from catalog data. `/lookup` only. |\n| `duration_ms` | Full track duration in milliseconds from catalog data. `/lookup` only. |\n| `explicit` | Boolean explicit flag from catalog data. `/lookup` only. |\n| `source` | Ingest source identifier. `/lookup` only. |\n| `first_ingested_at` | ISO 8601 UTC timestamp when the track was first added to the catalog. `/lookup` only. |\n| `mbid` | MusicBrainz Recording ID (UUID). `/lookup` only — cross-references the open music encyclopedia. |\n| `isrc` | International Standard Recording Code. `/lookup` only — uniquely identifies the master recording. |\n| `is_remix` | True if the recording is a third-party remix (parsed from the title). `/lookup` only. |\n| `remixer` | Remixer credited in the title, when attributable. `/lookup` only. |\n| `mix_name` | Mix/version label from the title (e.g. Extended Mix). `/lookup` only. |\n| `remix_of_isrc` | ISRC of the original recording a remix is based on. `/lookup` only. |\n| `itunes_track_id` | iTunes track ID (or `mb:`, `fma:`, `msd:` prefix for fallback sources). `/lookup` only. |\n\n### Endpoints beyond Spotify audio-features\n\n**Lookup & discovery**\n\n| Endpoint | Description |\n|---|---|\n| `GET /lookup` | Full feature set for one track — by name (+ artist), ISRC, MBID, or Spotify ID. |\n| `GET /bpm?bpm=128&tolerance=2` | Find catalog tracks by BPM. |\n| `GET /key?q=8A` | Find tracks by key (Camelot / Open Key / name). |\n| `GET /search?q=` | Full-text catalog search. |\n| `GET /artist/tracks` · `GET /genres` · `GET /genres/{name}/tracks` | Browse by artist or genre. |\n| `GET /charts/{country}` | Live national charts (45 countries). |\n| `POST /bulk` · `POST /bulk-csv` | Batch lookup (up to 50 / CSV up to 500 rows). |\n| `GET /v1/audio-features/{id}` · `?ids=` | Spotify-shape single + batch (up to 100). |\n\n**Harmonic Set Builder — set flow (the differentiator)**\n\n| Endpoint | Description |\n|---|---|\n| `GET /transition?from_track_id=&to_track_id=` | Score how cleanly two tracks mix, 0–100 (key + tempo + energy). 1 request. |\n| `GET /next-track?seed_track_id=` | Best next tracks for a seed, ranked by transition score. 3 requests. |\n| `POST /setlist` | Order a crate of 2–100 tracks into a beat-matched, energy-arced set. 5 requests. |\n| `GET /radio?seed_track_id=` | Harmonic + BPM-continuity playlist from a seed. 1 request. |\n| `GET /similar?track_id=` | Nearest tracks by feature embedding. |\n| `GET /export/{format}` | Export a playlist (Rekordbox XML / M3U8 / cuesheet). |\n\n**Recommendations (Spotify replacement) & tagging**\n\n| Endpoint | Description |\n|---|---|\n| `GET /recommendations?seed_tracks=` | Drop-in for Spotify's removed `/v1/recommendations` (1–5 seeds, genre-aware). 2 requests. |\n| `GET /related-artists?artist=` | Drop-in for Spotify's removed related-artists. 2 requests. |\n| `GET /tag?track=&artist=` | Compact mood / energy / genre tags with provenance. 1 request. |\n\n**Upload & identify**\n\n| Endpoint | Description |\n|---|---|\n| `POST /analyze` | Upload audio (≤15MB), get full analysis. 3 requests. |\n| `POST /identify` | Fingerprint + identify a recording (Chromaprint / AcoustID). 2 requests. |\n| `GET /track/{id}/artwork · /lyrics · /waveform.svg · /embedding` | Cover art, lyrics, waveform, feature vector. |\n\n**Old Spotify call** → `GET https://api.spotify.com/v1/audio-features/{id}` *(broken)*\n\n**This API** → `POST https://api.freqblog.com/analyze` with the audio file\n\n---\n\n### Privacy\n\nAudio is processed entirely in volatile memory and never written to disk.\nNo audio data is retained after the HTTP response is sent.\nMetadata results may be cached server-side by file hash for performance.\n\nOperated from the United Kingdom. GDPR-compliant data handling.\n", "contact": { "name": "FreqBlog", "url": "https://freqblog.com/", "email": "hello@freqblog.com" }, "license": { "name": "Commercial — see freqblog.com/terms.html", "url": "https://freqblog.com/terms.html" }, "version": "1.5.0" }, "servers": [ { "url": "https://api.freqblog.com", "description": "Production" } ], "paths": { "/lookup": { "get": { "tags": [ "Catalog" ], "summary": "Look up a track by name, ISRC, MusicBrainz ID, or Spotify ID", "description": "Search the pre-analyzed track catalog by track name and optional artist. Returns audio features instantly (< 10 ms) without uploading any audio.\n\n**Multi-tier catalog**: 270,000+ pre-analyzed tracks (refreshed daily from Apple Music charts — 45 country + 16 genre, iTunes Search categories, and Deezer charts; live count at `/cache/stats`) are returned instantly with the full feature set including `album_name`, `release_date`, `duration_ms`, `explicit`, `source`, and `first_ingested_at` alongside all audio features. If a track is not in the live catalog, a 4-layer fallback chain is attempted automatically — covering 8.5M+ additional tracks: MusicBrainz → AcousticBrainz (7.5M tracks, mood/genre/mood_vector) → FMA Echo Nest (13k tracks, valence) → Million Song Dataset (1M tracks, classic catalog). AcousticBrainz-sourced results include `bpm`, `key`, `danceability`, `acousticness`, `instrumentalness`, `mood`, `mood_vector`, `genre`, `mbid`, and `isrc`. `mood_vector` is also backfilled for catalog tracks when an AcousticBrainz match is found; `null` when no match exists. Fields that require audio (`energy`, `loudness_db`, `liveness`, `speechiness`, `valence`, `bpm_confidence`) are null for fallback tracks. The result is cached server-side so subsequent lookups are instant.\n\n**Track-name miss → 202 Accepted (on-demand ingest)**: if every fallback layer comes up empty for a `?track=&artist=` lookup, we return HTTP 202 + queue an on-demand ingest — typically ready in 30 s–2 min. Retry the same call shortly or watch progress in the dashboard. `?isrc=` / `?spotify_id=` paths return 404 on miss instead (no name+artist to drive the ingest).\n\n**This is the direct replacement for Spotify's deprecated `/audio-features/{id}` endpoint.** Look up by track name (`?track=...&artist=...`), by ISRC (`?isrc=USUM71900001` — the catalog is checked first, then MusicBrainz and Deezer resolve the recording on a miss), or by Spotify track ID (`?spotify_id=...` — resolves only tracks already mapped to a Spotify ID, a minority of the catalog; an arbitrary Spotify ID can't be reversed to a track server-side, so for others look up by `?track=&artist=`, or use `?isrc=` if your own Spotify integration already gives you the ISRC via `external_ids.isrc`), or by MusicBrainz recording ID (`?mbid=...` — features come straight from AcousticBrainz for that exact recording; the precise key when ISRC is absent or name matching is ambiguous; returns 404 when AcousticBrainz has no analysis for it). Supply exactly one of `track`, `isrc`, `mbid`, or `spotify_id`.", "operationId": "Lookup track", "parameters": [ { "name": "track", "in": "query", "required": false, "schema": { "description": "Track name (partial match supported). Supply this OR `isrc` OR `spotify_id`. For short titles (≤2 chars, e.g. Aphex Twin '4'), supply `artist` to anchor the search.", "title": "Track", "nullable": true, "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Track name (partial match supported). Supply this OR `isrc` OR `spotify_id`. For short titles (≤2 chars, e.g. Aphex Twin '4'), supply `artist` to anchor the search." }, { "name": "artist", "in": "query", "required": false, "schema": { "description": "Artist name (optional, narrows results — only used alongside `track`). Required when `track` is ≤2 characters.", "title": "Artist", "nullable": true, "type": "string", "maxLength": 200 }, "description": "Artist name (optional, narrows results — only used alongside `track`). Required when `track` is ≤2 characters." }, { "name": "isrc", "in": "query", "required": false, "schema": { "description": "ISRC, e.g. `USUM71900001`. Catalog is checked first, then MusicBrainz and Deezer resolve the recording on a miss — an unknown but resolvable ISRC is queued for on-demand ingest (HTTP 202). Supply this OR `track` OR `spotify_id`.", "title": "Isrc", "nullable": true, "type": "string", "maxLength": 15 }, "description": "ISRC, e.g. `USUM71900001`. Catalog is checked first, then MusicBrainz and Deezer resolve the recording on a miss — an unknown but resolvable ISRC is queued for on-demand ingest (HTTP 202). Supply this OR `track` OR `spotify_id`." }, { "name": "spotify_id", "in": "query", "required": false, "schema": { "description": "Spotify track ID (also accepts a `spotify:track:...` URI or open.spotify.com URL). Resolves ONLY tracks already mapped to a Spotify ID — a minority of the catalog (~2.4%) — so it is not a universal reverse lookup and 404s on unmapped IDs. For full coverage prefer `track` (+`artist`) or `isrc`. Supply this OR `track` OR `isrc` OR `mbid`.", "title": "Spotify Id", "nullable": true, "type": "string", "maxLength": 80 }, "description": "Spotify track ID (also accepts a `spotify:track:...` URI or open.spotify.com URL). Resolves ONLY tracks already mapped to a Spotify ID — a minority of the catalog (~2.4%) — so it is not a universal reverse lookup and 404s on unmapped IDs. For full coverage prefer `track` (+`artist`) or `isrc`. Supply this OR `track` OR `isrc` OR `mbid`." }, { "name": "mbid", "in": "query", "required": false, "schema": { "description": "MusicBrainz recording ID (UUID, e.g. `5b11f4ce-a62d-471e-81fc-a69a8278c7da`). Features are read straight from AcousticBrainz for that exact recording — the authoritative MBID→features path — so it's the precise key for cases where ISRC is absent (e.g. pre-1986 vinyl) or name matching is ambiguous. Returns 404 when AcousticBrainz has no analysis for the recording. Supply this OR `track` OR `isrc` OR `spotify_id`.", "title": "Mbid", "nullable": true, "type": "string", "maxLength": 40 }, "description": "MusicBrainz recording ID (UUID, e.g. `5b11f4ce-a62d-471e-81fc-a69a8278c7da`). Features are read straight from AcousticBrainz for that exact recording — the authoritative MBID→features path — so it's the precise key for cases where ISRC is absent (e.g. pre-1986 vinyl) or name matching is ambiguous. Returns 404 when AcousticBrainz has no analysis for the recording. Supply this OR `track` OR `isrc` OR `spotify_id`." }, { "name": "wait", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 25, "minimum": 0, "default": 0 }, "description": "Bounded synchronous wait in seconds (0–25). On a `track` miss, hold the request up to this long for the on-demand ingest to finish and return the analysed track inline (HTTP 200) instead of a 202 + re-poll — handy now that ingest is typically ~15s. Falls back to the normal 202 if it isn't ready in time. Default 0 = async. Name lookups only." } ], "responses": { "200": { "description": "Track found in catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackLookupResponse" }, "example": { "track_name": "Blinding Lights", "artist_name": "The Weeknd", "album_name": "After Hours", "itunes_track_id": "1488408568", "isrc": "CAUM71900002", "mbid": "5b11f4ce-a62d-471e-81fc-a69a8278c7da", "is_remix": false, "remixer": null, "mix_name": null, "remix_of_isrc": null, "release_date": "2019-11-29", "duration_ms": 200040, "explicit": false, "source": "apple_chart", "first_ingested_at": "2025-11-14T01:23:45", "bpm": 171.0, "bpm_confidence": 3.8, "key": "C#-Minor", "key_confidence": 0.76, "mode": 0, "camelot": "12A", "open_key": "5m", "energy": 0.91, "loudness_db": -7.1, "danceability": 0.76, "valence": 0.51, "mood": "energetic", "mood_vector": { "happy": 0.82, "sad": 0.04, "aggressive": 0.12, "relaxed": 0.31, "party": 0.77 }, "time_signature": 4, "acousticness": 0.04, "instrumentalness": 0.02, "liveness": 0.09, "speechiness": 0.06, "representative_segment_start": 62.0, "genre": "pop" } } } }, "202": { "description": "Track not found via `track` lookup — on-demand ingest queued; you will be notified when ready (per-track email under the daily cap, otherwise rolled into a daily digest)" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No analysable track. Three cases: (1) `isrc` / `spotify_id` resolved to nothing in the catalog, MusicBrainz, or Deezer; (2) a `track` lookup the pipeline has **already** terminally failed to ingest (no 30-second preview in any source); (3) an `mbid` whose recording has no AcousticBrainz analysis (the body carries the recording's identity so you can retry via `?isrc=` / `?track=`). Case (2) adds a `Retry-After` header (seconds) plus `terminal: true` and `retry_after_days` in the body so batch clients can stop polling. A *first-time* `track` miss returns 202 + queues an ingest instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Must supply exactly one of `track`, `isrc`, `mbid`, or `spotify_id` — or the `isrc`/`mbid` is malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded, or too many concurrent /lookup requests in flight for this key (carries `Retry-After`; space requests out or use `/bulk` for batches)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/audio-features/{identifier}": { "get": { "tags": [ "Spotify-compat" ], "summary": "Get audio features — Spotify-shape compatible", "description": "**Spotify-shape compatible replacement for the deprecated `GET /v1/audio-features/{id}`.** Change the host (`api.spotify.com` → `api.freqblog.com`) and the path + response field names match byte-for-byte: `acousticness`, `danceability`, `energy`, `instrumentalness`, `key` (0–11, `-1` if undetected), `liveness`, `loudness` (dB), `mode` (0/1), `speechiness`, `tempo` (BPM), `time_signature`, `valence`, plus `id` / `uri` / `track_href` / `analysis_url` / `duration_ms` / `type`.\n\n`{identifier}` is auto-detected: a 22-character base-62 string → Spotify track ID (also accepts `spotify:track:…` URIs and `open.spotify.com/track/…` URLs); a 12-character ISRC (e.g. `USUM71900001`, hyphens optional) → ISRC lookup (catalog first, then MusicBrainz resolves the recording on a miss). The Spotify-ID drop-in resolves **only tracks already mapped to a Spotify ID** (a minority of the catalog) — an arbitrary Spotify ID cannot be resolved to a track server-side, so this is not a universal Spotify-ID reverse lookup. For reliable coverage, identify tracks by **name or ISRC**: `GET /lookup?track=&artist=<artist>` searches the full catalog and queues an on-demand fetch + analysis on a miss; if your own Spotify integration already gives you the ISRC (`external_ids.isrc`), call this same route as `GET /v1/audio-features/<ISRC>` or `GET /lookup?isrc=<ISRC>`.\n\nNotes — the *values* are FreqBlog's own analysis (signal-analysis approximations: directionally compatible with Spotify's ML numbers, not numerically identical — see the [Field-by-Field Threshold Guide](https://freqblog.com/blog/spotify-audio-features-migration-thresholds/) for catalog distribution data and recommended threshold adjustments per field).\n\n**`?calibrate=spotify`** (opt-in) applies a per-field regression fitted on a 5,724-track overlap between our catalog and the public maharshipandya/spotify-tracks-dataset. v1 calibrates `loudness` only (R²=0.43, RMSE 3.0 dB vs raw 8.5 dB — 64% improvement). Other fields fall through unchanged because their heuristic-vs-ML methodology gap is too wide to ship a regression honestly. Default (omit `?calibrate=`) returns raw values.\n\n`analysis_url` is always `null` (no per-segment-analysis analog). For tracks resolved by ISRC, `uri` / `track_href` are `null` and `id` carries the ISRC, since we have no Spotify ID for the recording. Error bodies use FreqBlog's `{\"detail\": …}` shape, not Spotify's `{\"error\": {…}}`. Counts as one quota request. For batches, use the Spotify-shaped sibling: `GET /v1/audio-features?ids=…` (comma-separated, up to 100 IDs).", "operationId": "Audio features", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "A Spotify track ID (22-char base-62, or a `spotify:track:…` URI / open.spotify.com URL) — or an ISRC (12-char, e.g. `USUM71900001`; hyphens optional).", "title": "Identifier" }, "description": "A Spotify track ID (22-char base-62, or a `spotify:track:…` URI / open.spotify.com URL) — or an ISRC (12-char, e.g. `USUM71900001`; hyphens optional)." }, { "name": "calibrate", "in": "query", "required": false, "schema": { "description": "Set to `spotify` (lowercase, exact) to apply Spotify-scale calibration to numeric values. v1 calibrates loudness only (R²=0.43, RMSE 3.0 dB vs raw 8.5 dB — 64% improvement) using a linear regression fitted on a 5,724-track overlap with maharshipandya/spotify-tracks-dataset. Other fields fall through unchanged because their heuristic-vs-ML methodology gap is too wide to calibrate honestly; see the threshold guide for per-field details. Default (omit) returns raw FreqBlog values. Typos / case variants like `Spotify`, `SPOTIFY`, `true`, `1` will 422 — explicit rather than silently returning raw values.", "title": "Calibrate", "nullable": true, "enum": [ "spotify" ], "type": "string" }, "description": "Set to `spotify` (lowercase, exact) to apply Spotify-scale calibration to numeric values. v1 calibrates loudness only (R²=0.43, RMSE 3.0 dB vs raw 8.5 dB — 64% improvement) using a linear regression fitted on a 5,724-track overlap with maharshipandya/spotify-tracks-dataset. Other fields fall through unchanged because their heuristic-vs-ML methodology gap is too wide to calibrate honestly; see the threshold guide for per-field details. Default (omit) returns raw FreqBlog values. Typos / case variants like `Spotify`, `SPOTIFY`, `true`, `1` will 422 — explicit rather than silently returning raw values." } ], "responses": { "200": { "description": "Audio features in Spotify's `AudioFeaturesObject` shape", "content": { "application/json": { "schema": {}, "example": { "acousticness": 0.04, "danceability": 0.76, "duration_ms": 200040, "energy": 0.91, "id": "0VjIjW4GlUZAMYd2vXMi3b", "instrumentalness": 0.02, "key": 1, "liveness": 0.09, "loudness": -7.1, "mode": 0, "speechiness": 0.06, "tempo": 171.0, "time_signature": 4, "track_href": "https://api.spotify.com/v1/tracks/0VjIjW4GlUZAMYd2vXMi3b", "type": "audio_features", "uri": "spotify:track:0VjIjW4GlUZAMYd2vXMi3b", "valence": 0.51 } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No track found for that Spotify track ID / ISRC. This drop-in only covers tracks already mapped to a Spotify ID (a minority of the catalog) — an arbitrary Spotify ID can't be resolved server-side. For reliable coverage, identify the track by name (`GET /lookup?track=<title>&artist=<artist>`, which fetches on a miss) or by ISRC (`GET /lookup?isrc=<ISRC>`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "`identifier` is neither a 22-char Spotify track ID nor a 12-char ISRC", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded, or too many concurrent single-ID lookups for this key (per-key in-flight cap shared with /lookup; carries `Retry-After`). Space requests out, or send a large migration through the batch form `GET /v1/audio-features?ids=…`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The resolve exceeded its internal deadline (kept below the 30s gateway timeout) under load — transient, not a failure. Retry per `Retry-After`, or use the time-boxed batch form `GET /v1/audio-features?ids=…` / `POST /bulk`, which return partial results instead of timing out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/audio-features": { "get": { "tags": [ "Spotify-compat" ], "summary": "Get audio features for several tracks — Spotify-shape compatible (batch)", "description": "**Spotify-shape compatible replacement for the deprecated `GET /v1/audio-features?ids=…`.** Up to **100** comma-separated identifiers per request. Returns `{\"audio_features\": [...]}` — the array length and order match the input; entries are `null` for IDs that don't resolve (matching Spotify's behaviour).\n\nEach `ids` entry is auto-detected exactly like the single-ID route: a 22-char base-62 string → Spotify track ID (also accepts `spotify:track:…` URIs and `open.spotify.com/track/…` URLs); a 12-char ISRC (e.g. `USUM71900001`, hyphens optional) → ISRC lookup. Identifiers that match neither shape fill their slot with `null` rather than failing the whole batch.\n\nAs with the single-ID route, the Spotify-ID drop-in resolves **only tracks already mapped to a Spotify ID** (a minority of the catalog) — an arbitrary Spotify ID can't be reversed to a track server-side, so those slots come back `null`. For reliable coverage, identify tracks by **name or ISRC**: `GET /lookup?track=<title>&artist=<artist>` searches the full catalog and fetches on a miss, and ISRCs (e.g. from your own Spotify integration's `external_ids.isrc`) resolve via the same batch route or `GET /lookup?isrc=<ISRC>`.\n\n**Quota — one token per ID that returns data.** Each resolved ID counts as one quota request; IDs that come back `null` — an unmapped Spotify ID, an ISRC with no match, or one not resolved before the time-box — are **not** charged, exactly like the single-ID route, which is free on a 404 miss. So a 100-ID batch of raw Spotify IDs where only 5 are mapped bills 5, not 100. Spotify billed a 100-ID batch as 1 call; we bill per *resolved* ID, because each resolved lookup runs its own catalog query (and potentially a MusicBrainz roundtrip on an ISRC). See `/pricing` for higher tiers.\n\nOther notes from the single-ID route apply: the *values* are FreqBlog's analysis (signal-analysis approximations, directionally Spotify-compatible — see the [Field-by-Field Threshold Guide](https://freqblog.com/blog/spotify-audio-features-migration-thresholds/) for catalog distribution data and recommended threshold adjustments per field); `analysis_url` is always `null`; errors use FreqBlog's `{\"detail\": …}` shape, not Spotify's `{\"error\": {…}}`.\n\n**Resolved in parallel server-side, bounded for stability.** A large batch of uncatalogued IDs can take a while (each ISRC miss is a MusicBrainz roundtrip); if it exceeds the server time-box you get **partial results** — IDs resolved in time carry features, the rest come back `null` (and aren't charged) and resolve on a retry. A small number of `/bulk` + `/v1/audio-features` batch requests per key run at once — excess get `429` with `Retry-After`.", "operationId": "Audio features (batch)", "parameters": [ { "name": "ids", "in": "query", "required": false, "schema": { "description": "Comma-separated identifiers (max 100). Each is either a Spotify track ID (22-char base-62; also accepts `spotify:track:…` URIs and `open.spotify.com/track/…` URLs) or an ISRC (12-char, e.g. `USUM71900001`; hyphens optional). Only IDs that resolve to data are charged — unmapped IDs return `null` for free. No raw Spotify IDs? Identify tracks by name via `GET /lookup?track=<title>&artist=<artist>`.", "title": "Ids", "nullable": true, "type": "string", "example": "USUM71900001,003vvx7Niy0yvhvHt4a68B,USUMV1902060" }, "description": "Comma-separated identifiers (max 100). Each is either a Spotify track ID (22-char base-62; also accepts `spotify:track:…` URIs and `open.spotify.com/track/…` URLs) or an ISRC (12-char, e.g. `USUM71900001`; hyphens optional). Only IDs that resolve to data are charged — unmapped IDs return `null` for free. No raw Spotify IDs? Identify tracks by name via `GET /lookup?track=<title>&artist=<artist>`." }, { "name": "calibrate", "in": "query", "required": false, "schema": { "description": "Set to `spotify` (lowercase, exact) to apply Spotify-scale calibration to numeric values across the entire batch. Same calibration as the single-ID route: v1 calibrates loudness only (R²=0.43) from a 5,724-track public-dataset overlap. Typos / case variants 422 explicitly.", "title": "Calibrate", "nullable": true, "enum": [ "spotify" ], "type": "string" }, "description": "Set to `spotify` (lowercase, exact) to apply Spotify-scale calibration to numeric values across the entire batch. Same calibration as the single-ID route: v1 calibrates loudness only (R²=0.43) from a 5,724-track public-dataset overlap. Typos / case variants 422 explicitly." } ], "responses": { "200": { "description": "Batch audio features in Spotify's `{audio_features: [...]}` shape; entries are `null` for IDs that don't resolve (Spotify's behaviour)", "content": { "application/json": { "schema": {}, "example": { "audio_features": [ { "acousticness": 0.04, "danceability": 0.76, "energy": 0.91, "id": "0VjIjW4GlUZAMYd2vXMi3b", "key": 1, "mode": 0, "tempo": 171.0, "type": "audio_features", "uri": "spotify:track:0VjIjW4GlUZAMYd2vXMi3b", "...": "(remaining Spotify fields)" }, null, { "id": "USUM71900001", "key": 5, "tempo": 85.39, "type": "audio_features", "track_href": "https://api.freqblog.com/lookup?isrc=USUM71900001", "...": "(remaining Spotify fields)" } ] } } } }, "400": { "description": "`ids` missing, empty, or longer than 100. Supply `?ids=<comma-separated Spotify track IDs or 12-char ISRCs, up to 100>`. No raw Spotify IDs? Identify tracks by name via `GET /lookup?track=<title>&artist=<artist>`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota insufficient, or too many concurrent batch requests for this key (shared with /bulk)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Reserved for genuine service unavailability. The server time-box no longer fails a slow batch — IDs unresolved in time come back `null` in the 200 response (and aren't charged); retry to collect them.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/bulk": { "post": { "tags": [ "Catalog" ], "summary": "Bulk track lookup", "description": "Look up up to 50 tracks in a single request. Identify each item by name (`track`/`artist`) or by `isrc` — or both (`isrc` is matched exactly first, the name is the fallback). At least one of `isrc` or `track` is required (`title` is accepted as an alias for `track`). Because ISRC is exact, it resolves the CJK / K-pop / niche tracks whose fuzzy name-match misses. Each item is otherwise resolved through the same 4-layer fallback chain as `/lookup` (Apple Music catalog → MusicBrainz/AcousticBrainz → FMA Echo Nest → Million Song Dataset), covering 8.5M+ tracks. Tracks not found in any source return `found: false`; the `isrc` you supplied is echoed back on each result so you can map results onto ISRC-keyed inputs.\n\nResolvable-but-uncatalogued items are queued for on-demand ingest straight from the batch (paid plans, bounded per request) so a resolution pass warms the catalogue for your next call.\n\n**Quota** — charged per item that returns features OR queues an on-demand ingest; an ISRC/name with no match anywhere is free, as is one still processing at the 25-second server time-box (slow items come back `found=false` with `backfill_status=\"processing\"` — retry to collect them).", "operationId": "Bulk lookup", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BulkLookupItem" }, "maxItems": 50, "title": "Body" } } } }, "responses": { "200": { "description": "Bulk lookup complete (partial results possible)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkLookupResponse" } } } }, "400": { "description": "Request exceeds 50-track limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded, or too many concurrent /bulk requests for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Reserved for genuine service unavailability. The server time-box no longer fails a slow batch — tracks unresolved in time come back `found=false` with `backfill_status=\"processing\"` in the 200 response (and aren't charged); retry to collect them.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/bpm": { "get": { "tags": [ "Catalog" ], "summary": "Find tracks by BPM", "description": "Return catalog tracks within ±`tolerance` BPM of the target. No audio upload needed — instant lookup from the pre-analyzed catalog.\n\nResults are ordered by proximity to the target BPM, then by popularity. Use `tolerance=0.5` for exact-BPM matching or `tolerance=5` for a wider range.\n\n**Quota**: counts as one request regardless of how many tracks are returned.", "operationId": "Find by BPM", "parameters": [ { "name": "bpm", "in": "query", "required": false, "schema": { "description": "Target BPM", "title": "Bpm", "nullable": true, "type": "number", "maximum": 300.0, "minimum": 20.0 }, "description": "Target BPM" }, { "name": "tolerance", "in": "query", "required": false, "schema": { "type": "number", "maximum": 10.0, "minimum": 0.5, "description": "BPM tolerance window (±BPM)", "default": 2.0, "title": "Tolerance" }, "description": "BPM tolerance window (±BPM)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Maximum tracks to return", "default": 10, "title": "Limit" }, "description": "Maximum tracks to return" } ], "responses": { "200": { "description": "Tracks matching the BPM range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BpmSearchResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Missing or out-of-range `bpm`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/key": { "get": { "tags": [ "Catalog" ], "summary": "Find tracks by musical key", "description": "Return catalog tracks in the specified musical key. Accepts **Camelot** (e.g. `8A`), **Open Key** (e.g. `1m`), or a **key name** (e.g. `A-Minor`, `F#-Major`).\n\nResults are ordered by popularity descending. No audio upload needed — instant lookup from the pre-analyzed catalog.\n\n**Quota**: counts as one request regardless of how many tracks are returned.", "operationId": "Find by key", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 20, "description": "Key query: Camelot (8A), Open Key (1m), or key name (A-Minor)", "title": "Q" }, "description": "Key query: Camelot (8A), Open Key (1m), or key name (A-Minor)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Maximum tracks to return", "default": 10, "title": "Limit" }, "description": "Maximum tracks to return" } ], "responses": { "200": { "description": "Tracks matching the requested key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeySearchResponse" } } } }, "400": { "description": "Unrecognised key format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/search": { "get": { "tags": [ "Catalog" ], "summary": "Search the catalog by track / artist / album", "description": "Full-text search across track name, artist name, and album name. Returns lightweight track stubs (no audio features) ordered by relevance, then popularity. Use `/lookup` to fetch full audio features once you have a track id.\n\nEach whitespace-separated token is matched as a prefix (so `lov dean` matches *'Lover'* by *'Olivia Dean'*). Punctuation in the query is ignored.\n\n**Quota**: counts as one request regardless of how many results are returned.", "operationId": "Search catalog", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Search query (artist, track, album, or any combination).", "title": "Q" }, "description": "Search query (artist, track, album, or any combination)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Maximum results to return.", "default": 10, "title": "Limit" }, "description": "Maximum results to return." } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/artist/tracks": { "get": { "tags": [ "Catalog" ], "summary": "List catalog tracks for an artist", "description": "Returns lightweight track stubs for an artist (case-insensitive exact match on `artist_name`). Use `/search` first if you don't have an exact spelling, or `/lookup` to retrieve full audio features for any single track.\n\nOrdered by popularity descending, then track name. Supports pagination via `limit` + `offset`.\n\n**Quota**: counts as one request regardless of how many tracks are returned.", "operationId": "Artist tracks", "parameters": [ { "name": "artist", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Artist name (case-insensitive exact match).", "title": "Artist" }, "description": "Artist name (case-insensitive exact match)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum tracks to return.", "default": 20, "title": "Limit" }, "description": "Maximum tracks to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Pagination offset.", "default": 0, "title": "Offset" }, "description": "Pagination offset." } ], "responses": { "200": { "description": "Tracks for the requested artist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtistTracksResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No tracks for this artist in the catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/genres": { "get": { "tags": [ "Catalog" ], "summary": "List all genres in the catalog with track counts", "description": "Returns every distinct populated `genre` value in the catalog with the number of tracks tagged. Useful for building filter UIs or discovering coverage gaps.\n\nGenres come from AcousticBrainz (primary) and Last.fm (resolved by the background enrichment pipeline at ingest/backfill time — not on the synchronous lookup path), normalised (e.g. `raphiphop` → `hip-hop`, `folkcountry` → `folk`).\n\n**Quota**: counts as one request.", "operationId": "List genres", "parameters": [ { "name": "min_count", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 10000, "minimum": 1, "description": "Minimum track count for a genre to be included.", "default": 1, "title": "Min Count" }, "description": "Minimum track count for a genre to be included." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "description": "Maximum genres to return.", "default": 200, "title": "Limit" }, "description": "Maximum genres to return." } ], "responses": { "200": { "description": "List of genres in the catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenresResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/genres/{name}/tracks": { "get": { "tags": [ "Catalog" ], "summary": "List catalog tracks tagged with a genre", "description": "Returns lightweight track stubs tagged with the given genre (case-insensitive). Use the `/genres` endpoint to discover available genre names.\n\nOrdered by popularity descending, then track name. Supports pagination via `limit` + `offset`.\n\n**Quota**: counts as one request.", "operationId": "Genre tracks", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "description": "Genre name (case-insensitive).", "title": "Name" }, "description": "Genre name (case-insensitive)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum tracks to return.", "default": 20, "title": "Limit" }, "description": "Maximum tracks to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Pagination offset.", "default": 0, "title": "Offset" }, "description": "Pagination offset." } ], "responses": { "200": { "description": "Tracks tagged with the requested genre", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenreTracksResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No tracks for this genre in the catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/track/{itunes_track_id}/embedding": { "get": { "tags": [ "Catalog" ], "summary": "Numeric feature vector for a track", "description": "Project a track's audio features into a fixed-order numeric vector — convenient for similarity search, clustering, or feeding directly into your own ML model.\n\nThe `fields` array tells you what each position means. The `embedding_mask` array marks which positions came from real analysis (`true`) versus filled with a default (`false`) — use this to ignore filler positions in cosine-similarity calculations.\n\nLook up `itunes_track_id` values via `/search` or from any `/lookup` response.\n\n**Quota**: counts as one request.", "operationId": "Track embedding", "parameters": [ { "name": "itunes_track_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Catalog track id (or `mb:`/`fma:`/`msd:` synthetic id).", "title": "Itunes Track Id" }, "description": "Catalog track id (or `mb:`/`fma:`/`msd:` synthetic id)." } ], "responses": { "200": { "description": "Numeric feature vector for the track", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Track not in catalog or has no audio analysis", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/similar": { "get": { "tags": [ "Catalog" ], "summary": "Find acoustically similar tracks", "description": "Recommendation engine in one call. Pass a seed track id and get back the most acoustically similar tracks in the catalog, ranked by cosine similarity over an 18-feature audio embedding (BPM, key, energy, loudness, danceability, valence, mood, AcousticBrainz descriptors and more).\n\nPer-feature z-score normalisation runs at index build time using only real (non-default) values, so each feature contributes equally regardless of its raw scale. Filler values from missing features contribute zero to similarity — tracks with little real data don't poison the rankings.\n\n**Pass `track_id`** from any prior `/lookup`, `/search`, or `/bpm` response. Use `exclude_same_artist=true` to filter out other tracks by the same artist (useful for cross-artist recommendation feeds).\n\n**Quota**: counts as one request regardless of how many tracks are returned.", "operationId": "Similar tracks", "parameters": [ { "name": "track_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Seed track id (the catalog `itunes_track_id` from any prior response).", "title": "Track Id" }, "description": "Seed track id (the catalog `itunes_track_id` from any prior response)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Maximum results to return.", "default": 10, "title": "Limit" }, "description": "Maximum results to return." }, { "name": "exclude_same_artist", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Drop other tracks by the same artist as the seed.", "default": false, "title": "Exclude Same Artist" }, "description": "Drop other tracks by the same artist as the seed." } ], "responses": { "200": { "description": "Tracks ranked by audio-feature similarity to the seed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimilarResponse" } } } }, "400": { "description": "Seed track has too few real features to recommend from.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Seed track not found in catalog (or has no analysis).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/charts/{country}": { "get": { "tags": [ "Catalog" ], "summary": "Live national music chart (Apple Music)", "description": "Live top-songs chart for any of 45 supported countries, sourced from Apple Music RSS. Each entry is cross-referenced against the FreqBlog catalog — when the track is already analysed, `in_catalog=true` and `catalog_track` is populated with the full TrackStub (including `itunes_track_id` you can pass straight to `/lookup`, `/similar` or `/track/{id}/embedding`).\n\nSnapshots are cached for 12 hours per country/type/limit, so calling this is cheap.\n\n**Quota**: counts as one request.", "operationId": "National chart", "parameters": [ { "name": "country", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code, lowercase (e.g. `gb`, `us`, `jp`).", "title": "Country" }, "description": "ISO 3166-1 alpha-2 country code, lowercase (e.g. `gb`, `us`, `jp`)." }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "description": "Chart type: `most-played` (default) or `new-music`.", "default": "most-played", "title": "Type" }, "description": "Chart type: `most-played` (default) or `new-music`." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum chart entries to return.", "default": 50, "title": "Limit" }, "description": "Maximum chart entries to return." } ], "responses": { "200": { "description": "Live Apple Music chart for the country", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChartResponse" } } } }, "400": { "description": "Unsupported country code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream Apple RSS error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/radio": { "get": { "tags": [ "Catalog" ], "summary": "Generate a harmonic + BPM-continuity radio playlist", "description": "Build a continuous DJ-style playlist starting from a seed track. The walk is greedy: at each step we pick the most similar candidate that also satisfies harmonic mixing rules (Camelot wheel adjacency ≤ `max_key_distance`) and BPM continuity (within ±`bpm_drift` of the previous track).\n\nReturned tracks are in play order — the first entry equals the seed. Use this output directly with the export endpoints (`/export/rekordbox?track_ids=...`) to send a ready-to-mix playlist into Rekordbox or Serato.\n\n**Quota**: counts as one request regardless of `n`.", "operationId": "Radio playlist", "parameters": [ { "name": "seed_track_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Seed track id (catalog `itunes_track_id`).", "title": "Seed Track Id" }, "description": "Seed track id (catalog `itunes_track_id`)." }, { "name": "n", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 2, "description": "Total playlist length including the seed.", "default": 20, "title": "N" }, "description": "Total playlist length including the seed." }, { "name": "max_key_distance", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 12, "minimum": 0, "description": "Maximum Camelot-wheel hops between consecutive tracks. 1 = strict (same/adjacent/relative); 2 = relaxed; ≥3 = effectively no key constraint.", "default": 2, "title": "Max Key Distance" }, "description": "Maximum Camelot-wheel hops between consecutive tracks. 1 = strict (same/adjacent/relative); 2 = relaxed; ≥3 = effectively no key constraint." }, { "name": "bpm_drift", "in": "query", "required": false, "schema": { "type": "number", "maximum": 30.0, "minimum": 0.5, "description": "Max BPM difference between consecutive tracks.", "default": 8.0, "title": "Bpm Drift" }, "description": "Max BPM difference between consecutive tracks." }, { "name": "exclude_same_artist", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Drop tracks by the seed's artist from the entire playlist.", "default": false, "title": "Exclude Same Artist" }, "description": "Drop tracks by the seed's artist from the entire playlist." } ], "responses": { "200": { "description": "Harmonic playlist starting from the seed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadioResponse" } } } }, "400": { "description": "Seed has too little data to build a radio playlist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Seed track not in catalog (no audio analysis)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/transition": { "get": { "tags": [ "Catalog" ], "summary": "Score how well two tracks mix (harmonic + tempo + energy)", "description": "Score the transition FROM `from_track_id` INTO `to_track_id` on a 0-100 scale, blending Camelot-wheel key compatibility, octave-aware BPM proximity (half/double time counts), and energy smoothness — with a plain-English `reason`. This is set *flow*, not raw key/BPM — no competitor exposes pairwise transition scoring as an API.\n\nThe overall score is `0.50·harmonic + 0.30·tempo + 0.20·energy`. A missing key or BPM on a row doesn't hard-fail — the affected component falls back to a neutral 50 and `detail.key_relation` is reported as `unknown`.\n\nFind `itunes_track_id`s via `/search` or any `/lookup` response; chain `/next-track` → `/transition` → `/export/rekordbox`.\n\n**Quota**: counts as one request.", "operationId": "Score transition", "parameters": [ { "name": "from_track_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Track you're mixing OUT of (catalog `itunes_track_id`, or a `mb:`/`fma:`/`msd:` synthetic id).", "title": "From Track Id" }, "description": "Track you're mixing OUT of (catalog `itunes_track_id`, or a `mb:`/`fma:`/`msd:` synthetic id)." }, { "name": "to_track_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Track you're mixing INTO (catalog `itunes_track_id`, or a `mb:`/`fma:`/`msd:` synthetic id).", "title": "To Track Id" }, "description": "Track you're mixing INTO (catalog `itunes_track_id`, or a `mb:`/`fma:`/`msd:` synthetic id)." } ], "responses": { "200": { "description": "Mix-compatibility score for the from→to transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransitionResponse" } } } }, "400": { "description": "`from_track_id` and `to_track_id` are the same", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "One of the track ids is not in the catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/next-track": { "get": { "tags": [ "Catalog" ], "summary": "Ranked next-track suggestions for a seed (harmonic + tempo + energy)", "description": "Given a seed track, return the tracks that mix best after it: the seed's closest sonic neighbours, re-ranked by transition score (Camelot key + octave-aware BPM + energy). Each suggestion carries its overall score, the harmonic/tempo/energy component breakdown, and a plain-English `reason`.\n\nUse `min_score` to keep only clean mixes; `bpm_drift` and `max_key_distance` constrain the candidate pool before scoring. Find the seed `itunes_track_id` via `/search` or any `/lookup` response; chain the picks into `/transition` or `/export/rekordbox`.\n\n**Quota**: counts as 3 requests (it scores a large candidate pool).", "operationId": "Next track", "parameters": [ { "name": "seed_track_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Seed track id (catalog `itunes_track_id`).", "title": "Seed Track Id" }, "description": "Seed track id (catalog `itunes_track_id`)." }, { "name": "n", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Number of suggestions to return.", "default": 10, "title": "N" }, "description": "Number of suggestions to return." }, { "name": "min_score", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 0, "description": "Drop suggestions scoring below this overall value.", "default": 0, "title": "Min Score" }, "description": "Drop suggestions scoring below this overall value." }, { "name": "exclude_same_artist", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Skip tracks by the seed's artist.", "default": false, "title": "Exclude Same Artist" }, "description": "Skip tracks by the seed's artist." }, { "name": "bpm_drift", "in": "query", "required": false, "schema": { "type": "number", "maximum": 60.0, "minimum": 0.5, "description": "Max BPM difference (octave-aware) for a candidate to be considered.", "default": 12.0, "title": "Bpm Drift" }, "description": "Max BPM difference (octave-aware) for a candidate to be considered." }, { "name": "max_key_distance", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 12, "minimum": 0, "description": "Max Camelot-wheel hops for a candidate. 12 = no key constraint.", "default": 2, "title": "Max Key Distance" }, "description": "Max Camelot-wheel hops for a candidate. 12 = no key constraint." }, { "name": "cross_genre", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "auto", "allow", "strict" ], "description": "Genre handling. 'auto' (default) keeps picks in a mixable genre lane — an off-genre track that only coincidentally shares the key + BPM sinks to the bottom and appears only if too few in-genre picks exist. 'strict' = same genre-family only. 'allow' = genre-blind (pure harmonic + tempo + energy).", "default": "auto", "title": "Cross Genre" }, "description": "Genre handling. 'auto' (default) keeps picks in a mixable genre lane — an off-genre track that only coincidentally shares the key + BPM sinks to the bottom and appears only if too few in-genre picks exist. 'strict' = same genre-family only. 'allow' = genre-blind (pure harmonic + tempo + energy)." } ], "responses": { "200": { "description": "Ranked next-track suggestions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NextTrackResponse" } } } }, "400": { "description": "Seed has too little data to rank from", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Seed track not in catalog / similarity index", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Similarity index not yet built; try again shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/setlist": { "post": { "tags": [ "Catalog" ], "summary": "Order a crate into a beat-matched, energy-arced set", "description": "Give it a crate of catalog `itunes_track_id`s and it returns them **ordered** into a continuous set: each consecutive pair is harmonically + tempo compatible, and the set's energy follows the chosen `arc` (`peak_time` builds to a late peak then eases; `warmup` rises; `cooldown` falls; `flat` just optimises for smooth mixing). Greedy placement maximises transition score minus distance from the arc's energy target at each step.\n\nReturns the ordered `tracks`, the per-step `transitions` (with scores + reasons), and an overall `flow_score`. Chain into `/export/rekordbox?track_ids=...` (in the returned order) to drop the set straight into Rekordbox/Serato. Ids not in the catalog are returned in `omitted` and skipped.\n\n**Quota**: counts as 5 requests (it scores every candidate pair).", "operationId": "Build setlist", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetlistRequest" } } } }, "responses": { "200": { "description": "Tracks ordered into a beat-matched, energy-arced set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetlistResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "None of the supplied track ids are in the catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid body — need 2-100 `track_ids` and a known `arc` shape", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/export/{format}": { "get": { "tags": [ "Catalog" ], "summary": "Export tracks as a DJ playlist (Rekordbox / Serato / M3U / cuesheet)", "description": "Generate a DJ-ready file from a list of catalog `itunes_track_id`s.\n\n**Formats:**\n- `rekordbox` — Pioneer Rekordbox XML 1.0.0. Hot cue at the chorus / drop position. Most DJ software supports this format directly (Rekordbox, Engine DJ, Serato via XML import).\n- `m3u` — Extended M3U8 with BPM + Camelot in each EXTINF title. Read by Serato, Traktor, VirtualDJ, Engine DJ.\n- `cuesheet` — Plain-text cue sheet. Easy to paste into a notebook or share over chat.\n\nPair with `/radio?seed_track_id=...` to generate a harmonic playlist, then export it to your DJ software in one chained call.\n\n**Note:** the `Location` field references a synthetic path (`freqblog://<id>`); after import, relink each track to your local audio library — DJ software has built-in tools for this.\n\n**Quota**: counts as one request.", "operationId": "Export playlist", "parameters": [ { "name": "format", "in": "path", "required": true, "schema": { "type": "string", "description": "Output format: `rekordbox`, `m3u`, or `cuesheet`.", "title": "Format" }, "description": "Output format: `rekordbox`, `m3u`, or `cuesheet`." }, { "name": "track_ids", "in": "query", "required": true, "schema": { "type": "string", "description": "Comma-separated list of catalog `itunes_track_id`s, in playlist order.", "title": "Track Ids" }, "description": "Comma-separated list of catalog `itunes_track_id`s, in playlist order." } ], "responses": { "200": { "description": "DJ-ready file (XML / M3U / text).", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Unknown format or no track ids supplied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "None of the requested track ids are in the catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/bulk-csv": { "post": { "tags": [ "Catalog" ], "summary": "Bulk-enrich a CSV of (artist, title) pairs", "description": "Upload a CSV with `artist,title` columns and receive an enriched CSV with the full audio-features set appended to each row — BPM, key, mood, valence, danceability, energy, ISRC, MBID, and 28 more.\n\nHeader row is required and must contain `artist` and `title` (case-insensitive). Extra columns in the input are preserved in the output untouched.\n\n**Capacity**: up to 500 rows per request. Tracks not in the catalog or fallback chain return empty audio columns. Each data row with an artist and title counts as one quota request — headroom is verified before processing (`429` if the file is larger than your remaining quota) and charged only after the enrichment completes; a timed-out request (`503`) is never billed.\n\nForm field name: `file` (multipart/form-data).", "operationId": "Bulk CSV enrich", "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_bulk_csv_endpoint_bulk_csv_post" } } } }, "responses": { "200": { "description": "Enriched CSV with audio features per row.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "CSV parse error or no data rows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "More than 500 rows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota insufficient for the number of rows in the file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Enrichment timed out server-side and was cancelled — no quota charged. Split the file and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/track/{itunes_track_id}/artwork": { "get": { "tags": [ "Catalog" ], "summary": "Cover art for a track", "description": "302-redirect to a cover-art image for the track. Resolution order: iTunes Lookup API for numeric catalog ids, then Cover Art Archive via the track's MusicBrainz release IDs. The first hit is cached for 30 days (misses are also cached so we don't pummel upstream services).\n\n**Sizes**: 100, 200, 250, 300, 500, 600, 1000, 1200 — the closest supported size is used; iTunes URLs accept any of these, Cover Art Archive supports 250/500/1200.\n\n**Quota**: counts as one request.", "operationId": "Track cover art", "parameters": [ { "name": "itunes_track_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Catalog track id (numeric iTunes id, or `mb:`/`fma:`/`msd:`/`apple_<hash>` synthetic id).", "title": "Itunes Track Id" }, "description": "Catalog track id (numeric iTunes id, or `mb:`/`fma:`/`msd:`/`apple_<hash>` synthetic id)." }, { "name": "size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1200, "minimum": 100, "description": "Desired image size in pixels (square).", "default": 300, "title": "Size" }, "description": "Desired image size in pixels (square)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "302": { "description": "Redirect to the actual cover-art image." }, "400": { "description": "Invalid `size` parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No cover art available for this track.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/track/{itunes_track_id}/lyrics": { "get": { "tags": [ "Catalog" ], "summary": "Lyrics (plain + synced) for a catalog track", "description": "Returns synced + plain lyrics for a track via the open **LRClib** dataset. Lyrics are cached for 30 days per (track, artist) pair; cache misses are also cached so we don't repeatedly hit LRClib for tracks they don't have.\n\nSynced lyrics come back parsed: each entry is `{ms: int, text: str}` so you don't have to do LRC math client-side. Instrumentals return `instrumental: true` with empty lyrics arrays.\n\n**Quota**: counts as one request.", "operationId": "Track lyrics", "parameters": [ { "name": "itunes_track_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Catalog `itunes_track_id`.", "title": "Itunes Track Id" }, "description": "Catalog `itunes_track_id`." } ], "responses": { "200": { "description": "Lyrics payload (plain + synced) or instrumental flag.", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No lyrics found for this track", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/track/{itunes_track_id}/waveform.svg": { "get": { "tags": [ "Catalog" ], "summary": "SVG waveform for a track", "description": "Returns an SVG waveform render of the track's 30-second iTunes preview. The bucketed RMS values are cached for 90 days; SVG rendering happens at request time so callers can request any width/height without re-decoding audio.\n\nUse `currentColor` in your CSS to theme the waveform — every bar inherits the parent element's text colour. Defaults: 600×80.\n\nOnly works for catalog tracks with a numeric iTunes track id (the preview URL comes from iTunes Lookup). Synthetic ids (`mb:`/`fma:`/`msd:`/`apple_<hash>`) return 404.\n\n**Quota**: counts as one request.", "operationId": "Track waveform", "parameters": [ { "name": "itunes_track_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Numeric catalog `itunes_track_id`.", "title": "Itunes Track Id" }, "description": "Numeric catalog `itunes_track_id`." }, { "name": "w", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 2400, "minimum": 120, "description": "SVG width in pixels.", "default": 600, "title": "W" }, "description": "SVG width in pixels." }, { "name": "h", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 400, "minimum": 20, "description": "SVG height in pixels.", "default": 80, "title": "H" }, "description": "SVG height in pixels." } ], "responses": { "200": { "description": "SVG waveform image.", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No audio preview available for this track", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/recommendations": { "get": { "tags": [ "Catalog" ], "summary": "Recommended tracks for seed tracks (Spotify /recommendations replacement)", "description": "**The drop-in for Spotify's removed `GET /v1/recommendations`** (deprecated November 2024, fully retired since). Supply 1-5 catalog `itunes_track_id`s as `seed_tracks`; we blend them into a single point in audio-feature space (a centroid over an 18-feature embedding — BPM, key, energy, loudness, danceability, valence, mood, AcousticBrainz descriptors and more) and return the nearest catalogue tracks, **re-ranked by genre affinity** so a feature-close cross-genre track doesn't outrank same-genre picks.\n\nBuilt on FreqBlog's own audio-feature similarity index + catalogue genre (94% coverage) — no Spotify account, no deprecated endpoint, no ListenBrainz dependency. Seeds are FreqBlog `itunes_track_id`s (e.g. `apple_ad1829eeccb70f9a`), taken from `/search` or any `/lookup` response.\n\n`score` is the raw audio-feature cosine similarity (genre affinity influences **ordering**, not the score), so the returned list is **not** strictly score-descending. Each seed is echoed back in `seeds` with a `found` flag so you can tell which ids were usable.\n\n**No id?** Pass `track` + `artist` instead of `seed_tracks` and we resolve the name to the best catalogue match (echoed back as `seed_query` so you can confirm it) and seed on it; `seed_tracks` wins if both are sent. A name we don't yet have returns 404 — `/lookup` it first.\n\n**Quota**: counts as 2 requests.", "operationId": "Recommendations", "parameters": [ { "name": "seed_tracks", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma-separated catalog `itunes_track_id`s (1-5). Recommendations are based on their blended feature-space centroid. Omit and use `track`(+`artist`) to seed by name instead.", "title": "Seed Tracks", "example": "apple_ad1829eeccb70f9a" }, "description": "Comma-separated catalog `itunes_track_id`s (1-5). Recommendations are based on their blended feature-space centroid. Omit and use `track`(+`artist`) to seed by name instead." }, { "name": "track", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200, "description": "Seed by track NAME instead of an id — resolved to the best catalogue match (echoed back as `seed_query`). Pair with `artist` to disambiguate. Ignored when `seed_tracks` is supplied.", "title": "Track", "example": "Got to Be Real" }, "description": "Seed by track NAME instead of an id — resolved to the best catalogue match (echoed back as `seed_query`). Pair with `artist` to disambiguate. Ignored when `seed_tracks` is supplied." }, { "name": "artist", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200, "description": "Artist name narrowing the `track` seed (case-insensitive).", "title": "Artist", "example": "Cheryl Lynn" }, "description": "Artist name narrowing the `track` seed (case-insensitive)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Number of recommendations to return.", "default": 20, "title": "Limit" }, "description": "Number of recommendations to return." }, { "name": "exclude_seed_artists", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Drop tracks by any of the seed artists from the results.", "default": false, "title": "Exclude Seed Artists" }, "description": "Drop tracks by any of the seed artists from the results." }, { "name": "cross_genre", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "auto", "allow", "strict" ], "description": "Genre handling. 'auto' (default) re-ranks by genre affinity so a feature-close cross-genre track can't outrank same-genre picks, while cross-genre picks still appear (result never shorter). 'strict' = same genre-family only (off-genre matches dropped server-side). 'allow' = genre-blind (pure audio-feature cosine).", "default": "auto", "title": "Cross Genre" }, "description": "Genre handling. 'auto' (default) re-ranks by genre affinity so a feature-close cross-genre track can't outrank same-genre picks, while cross-genre picks still appear (result never shorter). 'strict' = same genre-family only (off-genre matches dropped server-side). 'allow' = genre-blind (pure audio-feature cosine)." } ], "responses": { "200": { "description": "Recommended tracks for the seed blend", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecommendationsResponse" } } } }, "400": { "description": "No seed supplied — provide `seed_tracks` (1-5 catalog track ids) or a `track` name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "None of the seed tracks are in the catalog (or have enough audio features) to recommend from", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Similarity index not yet built — try again shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/related-artists": { "get": { "tags": [ "Catalog" ], "summary": "Artists related to a seed artist (Spotify related-artists replacement)", "description": "**The drop-in for Spotify's removed `GET /v1/artists/{id}/related-artists`** (deprecated November 2024, fully retired since). Pass an artist `name`; since no artist graph exists we derive one on the fly: we build the seed artist's track-vector centroid from their catalogue tracks, find the nearest tracks in audio-feature space, then aggregate those by artist.\n\nEach candidate artist is scored on its **top-3 track similarities** (so a prolific catalogue artist can't dominate purely on volume) plus a same-genre lift and a cross-genre penalty. Built on FreqBlog's own similarity index + catalogue genre (94% coverage) — no Spotify account, no artist-relations graph required.\n\nEach result carries a `sample_track_id` you can feed straight to `/lookup`, `/similar`, or `/next-track`. Real example: `/related-artists?artist=Van%20Halen` leads with Danger Danger, AC/DC, Def Leppard.\n\n**Quota**: counts as 2 requests.", "operationId": "Related artists", "parameters": [ { "name": "artist", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Seed artist name (as it appears in the catalog; case-insensitive).", "title": "Artist", "example": "Van Halen" }, "description": "Seed artist name (as it appears in the catalog; case-insensitive)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Number of related artists to return.", "default": 20, "title": "Limit" }, "description": "Number of related artists to return." } ], "responses": { "200": { "description": "Artists related to the seed artist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelatedArtistsResponse" } } } }, "400": { "description": "No artist supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Seed artist not found in the catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Similarity index not yet built — try again shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/tag": { "get": { "tags": [ "Catalog" ], "summary": "Compact descriptive tags for a track (mood / energy / genre, with provenance)", "description": "Returns a compact, **honestly-labelled** tag array for a track — a tag-shaped projection of the same open-data analysis `/lookup` returns (no upload, no extra compute). Resolve by exactly ONE of `track`(+`artist`), `isrc`, `mbid`, `spotify_id`, or catalog `track_id`.\n\nEvery tag carries a `confidence` (`measured` = our Essentia analysis | `derived` = MIREX mood from valence+energy | `model-estimated` = AcousticBrainz mood SVM probability, raw prob in `value` | `catalog-genre` = broad catalogue tag) and a `provenance` — the honesty is the point, vs opaque taggers. `value` is the [0,1] score for numeric tags, null for label-only tags.\n\nThe broad, reliable coverage is the MEASURED tags from our analysis (the analysed catalogue + on-demand by name); MBID/ISRC additionally reach 7.5M+ AcousticBrainz recordings WHEN you supply that identifier. For the full numeric feature set use `/lookup`; for nearest tracks use `/similar`.\n\n**Quota**: 1 request.", "operationId": "Tag", "parameters": [ { "name": "track", "in": "query", "required": false, "schema": { "type": "string", "title": "Track", "description": "Track name. Supply this OR `isrc`/`mbid`/`spotify_id`/`track_id`." }, "description": "Track name. Supply this OR `isrc`/`mbid`/`spotify_id`/`track_id`." }, { "name": "artist", "in": "query", "required": false, "schema": { "type": "string", "title": "Artist", "description": "Artist name (narrows `track`; required when `track` ≤2 chars)." }, "description": "Artist name (narrows `track`; required when `track` ≤2 chars)." }, { "name": "isrc", "in": "query", "required": false, "schema": { "type": "string", "title": "Isrc", "description": "ISRC, e.g. `USUM71900001`." }, "description": "ISRC, e.g. `USUM71900001`." }, { "name": "mbid", "in": "query", "required": false, "schema": { "type": "string", "title": "Mbid", "description": "MusicBrainz recording ID (UUID) — tags read straight from AcousticBrainz for that recording." }, "description": "MusicBrainz recording ID (UUID) — tags read straight from AcousticBrainz for that recording." }, { "name": "spotify_id", "in": "query", "required": false, "schema": { "type": "string", "title": "Spotify Id", "description": "Spotify track ID — resolves ONLY tracks already mapped to a Spotify ID (~2.4% of the catalog); prefer track (+artist) or isrc for full coverage." }, "description": "Spotify track ID — resolves ONLY tracks already mapped to a Spotify ID (~2.4% of the catalog); prefer track (+artist) or isrc for full coverage." }, { "name": "track_id", "in": "query", "required": false, "schema": { "type": "string", "title": "Track Id", "description": "Catalog `itunes_track_id` (from `/search` or any `/lookup`)." }, "description": "Catalog `itunes_track_id` (from `/search` or any `/lookup`)." } ], "responses": { "200": { "description": "Tags for the resolved track", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagResponse" } } } }, "400": { "description": "Short track name needs an `artist`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Track not found or not yet analysed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Supply exactly one identifier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Monthly quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "schemas": { "ArtistTracksResponse": { "properties": { "artist": { "type": "string", "title": "Artist", "description": "Artist name as submitted (case preserved)." }, "total": { "type": "integer", "title": "Total", "description": "Total tracks in catalog for this artist (independent of `limit`/`offset`)." }, "count": { "type": "integer", "title": "Count", "description": "Number of tracks in this response page." }, "tracks": { "items": { "$ref": "#/components/schemas/TrackStub" }, "type": "array", "title": "Tracks" } }, "type": "object", "required": [ "artist", "total", "count", "tracks" ], "title": "ArtistTracksResponse" }, "AudioAnalysisResponse": { "properties": { "bpm": { "type": "number", "maximum": 300.0, "minimum": 20.0, "title": "Bpm", "description": "Tempo in beats per minute. Equivalent to Spotify's `tempo` field.", "example": 128.0 }, "bpm_alt": { "title": "Bpm Alt", "description": "Half-time/double-time corrected alternative BPM, when our heuristic suggests the detected `bpm` may be off by a factor of 2. Null when no correction is warranted. Never replaces `bpm`.", "nullable": true, "type": "number", "example": 256.0 }, "bpm_confidence": { "type": "number", "title": "Bpm Confidence", "description": "Beat-strength score from Essentia's RhythmExtractor2013. Higher = stronger rhythmic pulse. Typical range 0–10. Values below 1.0 indicate weak or absent rhythm (ambient, spoken word).", "example": 4.12 }, "key": { "type": "string", "title": "Key", "description": "Musical key and scale as a human-readable string, e.g. `A-Minor` or `F#-Major`. Combines Spotify's integer `key` + `mode` fields into one readable value.", "example": "A-Minor" }, "key_confidence": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Key Confidence", "description": "Key detection confidence [0–1]. Below 0.4 indicates atonal, modal, or harmonically ambiguous content. Equivalent to Spotify's implicit key reliability.", "example": 0.83 }, "mode": { "title": "Mode", "description": "Musical mode as a Spotify-compatible integer: `0` = minor, `1` = major. Direct drop-in for Spotify's deprecated `mode` field.", "nullable": true, "type": "integer", "maximum": 1.0, "minimum": 0.0, "example": 0 }, "key_int": { "title": "Key Int", "description": "Pitch-class integer for the key, Spotify-compatible: `0` = C, `1` = C♯/D♭, `2` = D, … `11` = B. `null` when the key is undetected/atonal (Spotify used `-1`).", "nullable": true, "type": "integer", "maximum": 11.0, "minimum": 0.0, "example": 1 }, "camelot": { "title": "Camelot", "description": "Camelot wheel notation for harmonic mixing, e.g. `8A` (A-Minor) or `5B` (D-Major). Used by DJs to find harmonically compatible tracks. A = minor keys, B = major keys. Numbers 1–12.", "nullable": true, "type": "string", "example": "8A" }, "open_key": { "title": "Open Key", "description": "Open Key notation for harmonic mixing, e.g. `1m` (A-Minor) or `1d` (C-Major). Alternative to Camelot — used by Serato DJ and Mixed In Key. d = major (dominant), m = minor. Numbers 1–12.", "nullable": true, "type": "string", "example": "1m" }, "acousticness": { "title": "Acousticness", "description": "Confidence that the track is acoustic [0–1]. Derived from spectral flatness — low flatness = more tonal/acoustic. Equivalent to Spotify's `acousticness` field.", "nullable": true, "type": "number", "maximum": 1.0, "minimum": 0.0, "example": 0.21 }, "danceability": { "title": "Danceability", "description": "How suitable the track is for dancing [0–1]. Based on tempo (peaks at 120 BPM), beat strength, and rhythmic regularity. Equivalent to Spotify's `danceability` field.", "nullable": true, "type": "number", "maximum": 1.0, "minimum": 0.0, "example": 0.78 }, "instrumentalness": { "title": "Instrumentalness", "description": "Likelihood the track contains no vocals [0–1]. Derived from MFCC variance in vocal-formant frequency ranges. Equivalent to Spotify's `instrumentalness` field.", "nullable": true, "type": "number", "maximum": 1.0, "minimum": 0.0, "example": 0.04 }, "liveness": { "title": "Liveness", "description": "Likelihood the track was performed live [0–1]. Derived from the noise floor ratio (audience/room ambience proxy). Equivalent to Spotify's `liveness` field.", "nullable": true, "type": "number", "maximum": 1.0, "minimum": 0.0, "example": 0.09 }, "speechiness": { "title": "Speechiness", "description": "Presence of spoken words [0–1]. Derived from zero-crossing rate — high ZCR indicates speech or rap. Equivalent to Spotify's `speechiness` field.", "nullable": true, "type": "number", "maximum": 1.0, "minimum": 0.0, "example": 0.06 }, "valence": { "title": "Valence", "description": "Musical positiveness [0–1]. High = happy/euphoric, low = sad/dark. Derived from scale (major/minor), tempo, spectral brightness, and energy. Equivalent to Spotify's `valence` field.", "nullable": true, "type": "number", "maximum": 1.0, "minimum": 0.0, "example": 0.54 }, "mood": { "title": "Mood", "description": "MIREX-style mood category derived from valence and energy. One of: happy, calm, sad, tense, energetic, melancholic, neutral. Maps the four-quadrant mood model: high valence + high energy = happy; low valence + high energy = tense; etc.", "nullable": true, "type": "string", "example": "happy" }, "representative_segment_start": { "title": "Representative Segment Start", "description": "Start time in seconds of the highest-energy 30-second window. Identifies the most sonically representative (e.g. chorus or drop) segment. Useful for sync licensing, preview generation, and waveform thumbnails. 0.0 for tracks ≤ 30 s.", "nullable": true, "type": "number", "example": 62.0 }, "rms_energy": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Rms Energy", "description": "Normalised RMS loudness [0–1]. Comparable to Spotify's `energy` field — both measure perceptual intensity. Computed over the same 30-second window as BPM and key.", "example": 0.74 }, "loudness_db": { "title": "Loudness Db", "description": "Integrated loudness in dBFS (decibels relative to full scale). Equivalent to Spotify's `loudness` field. Typical mastered pop/electronic: -10 to -5 dBFS. Quiet/acoustic: -20 to -15.", "nullable": true, "type": "number", "example": -7.4 }, "time_signature": { "title": "Time Signature", "description": "Estimated time signature (bar grouping). Equivalent to Spotify's `time_signature` field. Most tracks return 4 (4/4). Values: 2, 3, 4, 5, 6, 7.", "nullable": true, "type": "integer", "example": 4 }, "mood_vector": { "title": "Mood Vector", "description": "Dimensional mood scores [0–1] across five axes: `happy`, `sad`, `aggressive`, `relaxed`, `party`. Populated when an AcousticBrainz high-level match is found; `null` otherwise. Use these for fine-grained mood filtering beyond the single-label `mood` field.", "nullable": true, "additionalProperties": { "type": "number" }, "type": "object", "example": { "aggressive": 0.12, "happy": 0.82, "party": 0.77, "relaxed": 0.31, "sad": 0.04 } }, "cached": { "type": "boolean", "title": "Cached", "description": "True if this result was served from the server-side cache. Cached responses are < 100 ms. The underlying analysis is identical to a fresh result.", "default": false } }, "type": "object", "required": [ "bpm", "bpm_confidence", "key", "key_confidence", "rms_energy" ], "title": "AudioAnalysisResponse" }, "Body_analyze_endpoint_analyze_post": { "properties": { "file": { "type": "string", "format": "binary", "title": "File", "description": "Audio file (MP3, WAV, OGG, FLAC, AAC/M4A)" } }, "type": "object", "required": [ "file" ], "title": "Body_analyze_endpoint_analyze_post" }, "Body_bulk_csv_endpoint_bulk_csv_post": { "properties": { "file": { "type": "string", "format": "binary", "title": "File", "description": "CSV file with `artist,title` columns." } }, "type": "object", "required": [ "file" ], "title": "Body_bulk_csv_endpoint_bulk_csv_post" }, "Body_identify_endpoint_identify_post": { "properties": { "file": { "type": "string", "format": "binary", "title": "File", "description": "Audio file (any format ffmpeg can decode, max 15 MB)" } }, "type": "object", "required": [ "file" ], "title": "Body_identify_endpoint_identify_post" }, "BpmSearchResponse": { "properties": { "bpm": { "type": "number", "title": "Bpm", "description": "Target BPM queried." }, "tolerance": { "type": "number", "title": "Tolerance", "description": "Tolerance window applied (±BPM)." }, "count": { "type": "integer", "title": "Count", "description": "Number of tracks returned." }, "tracks": { "items": { "$ref": "#/components/schemas/TrackLookupResponse" }, "type": "array", "title": "Tracks" } }, "type": "object", "required": [ "bpm", "tolerance", "count", "tracks" ], "title": "BpmSearchResponse" }, "BulkLookupItem": { "properties": { "track": { "type": "string", "maxLength": 200, "nullable": true, "title": "Track", "description": "Track name (partial match supported). Supply this OR `isrc` (or both — `isrc` is matched exactly first, the name is the fallback). `title` is also accepted as an alias. For short titles (≤2 chars, e.g. Aphex Twin '4'), supply `artist` to anchor the search.", "example": "Blinding Lights" }, "artist": { "title": "Artist", "description": "Artist name (optional, narrows the name search).", "nullable": true, "type": "string", "maxLength": 200, "example": "The Weeknd" }, "isrc": { "type": "string", "maxLength": 15, "nullable": true, "title": "Isrc", "description": "ISRC (e.g. `USUM71900001`, hyphens optional). Matched exactly first — resolves CJK / K-pop / niche tracks whose fuzzy name-match misses. Supply this OR `track`.", "example": "USUM71900001" } }, "type": "object", "title": "BulkLookupItem" }, "BulkLookupResponse": { "properties": { "results": { "items": { "$ref": "#/components/schemas/BulkTrackResult" }, "type": "array", "title": "Results" }, "found": { "type": "integer", "title": "Found", "description": "Number of tracks found in the catalog." }, "not_found": { "type": "integer", "title": "Not Found", "description": "Number of tracks not found." }, "requests_used": { "type": "integer", "title": "Requests Used", "description": "Number of quota requests consumed by this call." } }, "type": "object", "required": [ "results", "found", "not_found", "requests_used" ], "title": "BulkLookupResponse" }, "BulkTrackResult": { "properties": { "track": { "type": "string", "title": "Track", "description": "Track name as submitted (null for ISRC-only items).", "nullable": true }, "artist": { "title": "Artist", "description": "Artist name as submitted in the request.", "nullable": true, "type": "string" }, "isrc": { "type": "string", "nullable": true, "title": "Isrc", "description": "ISRC for this item, when one was supplied — echoed back so you can map results onto ISRC-keyed inputs." }, "found": { "type": "boolean", "title": "Found", "description": "True if the track was found in any source (catalog or fallback chain)." }, "result": { "description": "Audio features. Null if track not found.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TrackLookupResponse" } ] }, "backfill_status": { "title": "Backfill Status", "description": "`queued` when a field-backfill or on-demand ingest was started for this item; `processing` when the server time-box was hit before it resolved (retry to collect it); null otherwise.", "nullable": true, "type": "string" } }, "type": "object", "required": [ "found" ], "title": "BulkTrackResult" }, "CamelotCompatibleResponse": { "properties": { "input_camelot": { "type": "string", "title": "Input Camelot", "description": "Input Camelot notation as parsed.", "example": "8A" }, "input_key": { "type": "string", "title": "Input Key", "description": "Input as a human-readable key.", "example": "A-Minor" }, "compatible": { "items": { "$ref": "#/components/schemas/KeyVariant" }, "type": "array", "title": "Compatible", "description": "Keys that mix harmonically with the input. Always includes `same`, `relative`, `adjacent_up`, `adjacent_down`. With `extended=true` also includes `energy_boost` and `energy_drop`." } }, "type": "object", "required": [ "input_camelot", "input_key", "compatible" ], "title": "CamelotCompatibleResponse" }, "ChartEntry": { "properties": { "rank": { "type": "integer", "title": "Rank", "description": "Position on the chart, 1-indexed." }, "itunes_track_id": { "title": "Itunes Track Id", "description": "iTunes track id from the chart feed.", "nullable": true, "type": "string" }, "track_name": { "type": "string", "title": "Track Name" }, "artist_name": { "type": "string", "title": "Artist Name" }, "album_name": { "title": "Album Name", "nullable": true, "type": "string" }, "artwork_url": { "title": "Artwork Url", "description": "100×100 artwork from Apple, when available.", "nullable": true, "type": "string" }, "release_date": { "title": "Release Date", "nullable": true, "type": "string" }, "in_catalog": { "type": "boolean", "title": "In Catalog", "description": "True if this track is already analysed in the FreqBlog catalog (call /lookup or /track/{id}/embedding to retrieve features)." }, "catalog_track": { "description": "Catalog row when `in_catalog=true`, including any populated `mbid`, `isrc`, `genre`.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TrackStub" } ] } }, "type": "object", "required": [ "rank", "track_name", "artist_name", "in_catalog" ], "title": "ChartEntry" }, "ChartResponse": { "properties": { "country": { "type": "string", "title": "Country", "description": "ISO 3166-1 alpha-2 country code as queried.", "example": "gb" }, "type": { "type": "string", "title": "Type", "description": "Chart type. Currently `most-played` (Apple's daily top songs)." }, "fetched_at": { "type": "string", "title": "Fetched At", "description": "ISO 8601 timestamp this chart snapshot was fetched. Cached for 12 hours." }, "count": { "type": "integer", "title": "Count" }, "entries": { "items": { "$ref": "#/components/schemas/ChartEntry" }, "type": "array", "title": "Entries" } }, "type": "object", "required": [ "country", "type", "fetched_at", "count", "entries" ], "title": "ChartResponse" }, "EmbeddingResponse": { "properties": { "itunes_track_id": { "type": "string", "title": "Itunes Track Id", "example": "1488408568" }, "track_name": { "type": "string", "title": "Track Name", "example": "Blinding Lights" }, "artist_name": { "type": "string", "title": "Artist Name", "example": "The Weeknd" }, "dim": { "type": "integer", "title": "Dim", "description": "Length of the embedding vector.", "example": 18 }, "fields": { "items": { "type": "string" }, "type": "array", "title": "Fields", "description": "Field name for each position in `embedding`. Always returned in a stable order so callers can rely on positional indexing." }, "embedding": { "items": { "type": "number" }, "type": "array", "title": "Embedding", "description": "Numeric feature vector. Missing values are filled with sensible defaults (see `embedding_mask`)." }, "embedding_mask": { "items": { "type": "boolean" }, "type": "array", "title": "Embedding Mask", "description": "Per-position truthy when the value came from real analysis, falsy when filled with a default. Use to mask out filler values in similarity calculations." } }, "type": "object", "required": [ "itunes_track_id", "track_name", "artist_name", "dim", "fields", "embedding", "embedding_mask" ], "title": "EmbeddingResponse", "description": "Numeric feature vector for a track — convenient for ML / similarity / clustering." }, "ErrorResponse": { "properties": { "detail": { "type": "string", "title": "Detail" }, "error_code": { "title": "Error Code", "nullable": true, "type": "string" } }, "type": "object", "required": [ "detail" ], "title": "ErrorResponse" }, "ExtendedAudioFeatures": { "properties": { "gender": { "title": "Gender", "description": "Vocal gender classification: `male` / `female`. Inferred from MFCC + F0 features. Best for tracks with sustained vocals; less reliable on instrumentals or short clips.", "nullable": true, "type": "string", "example": "female" }, "timbre": { "title": "Timbre", "description": "Timbral brightness classification: `bright` / `dark`. Bright = strong high-frequency content (cymbals, electric guitar); dark = bass-dominant.", "nullable": true, "type": "string", "example": "bright" }, "tonal_atonal": { "title": "Tonal Atonal", "description": "Tonality classification: `tonal` / `atonal`. Tonal = clear key centre; atonal = ambiguous or shifting tonality (typical of avant-garde / drone).", "nullable": true, "type": "string", "example": "tonal" } }, "type": "object", "title": "ExtendedAudioFeatures", "description": "Higher-level categorical labels from AcousticBrainz. Each value is the\nmost-confident class from a binary classifier — useful for filtering /\nbucketing but not for fine-grained analysis." }, "FreeKeyRequest": { "properties": { "email": { "type": "string", "title": "Email" }, "name": { "type": "string", "title": "Name", "default": "" }, "turnstile_token": { "type": "string", "title": "Turnstile Token", "default": "" }, "utm_source": { "type": "string", "title": "Utm Source", "default": "" }, "utm_medium": { "type": "string", "title": "Utm Medium", "default": "" }, "utm_campaign": { "type": "string", "title": "Utm Campaign", "default": "" } }, "type": "object", "required": [ "email" ], "title": "FreeKeyRequest" }, "GenreInfo": { "properties": { "genre": { "type": "string", "title": "Genre", "example": "electronic" }, "track_count": { "type": "integer", "title": "Track Count", "description": "Number of catalog tracks tagged with this genre." } }, "type": "object", "required": [ "genre", "track_count" ], "title": "GenreInfo" }, "GenreTracksResponse": { "properties": { "genre": { "type": "string", "title": "Genre" }, "total": { "type": "integer", "title": "Total", "description": "Total tracks in catalog for this genre (independent of `limit`/`offset`)." }, "count": { "type": "integer", "title": "Count" }, "tracks": { "items": { "$ref": "#/components/schemas/TrackStub" }, "type": "array", "title": "Tracks" } }, "type": "object", "required": [ "genre", "total", "count", "tracks" ], "title": "GenreTracksResponse" }, "GenresResponse": { "properties": { "count": { "type": "integer", "title": "Count", "description": "Number of distinct genres returned." }, "genres": { "items": { "$ref": "#/components/schemas/GenreInfo" }, "type": "array", "title": "Genres", "description": "Genres ordered by track_count descending." } }, "type": "object", "required": [ "count", "genres" ], "title": "GenresResponse" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "IdentifyResponse": { "properties": { "matched": { "type": "boolean", "title": "Matched", "description": "True when the fingerprint matched a known recording in the AcoustID database." }, "score": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Score", "description": "AcoustID match confidence, 0–1.", "example": 0.94 }, "acoustid": { "title": "Acoustid", "description": "AcoustID UUID for the recording group, when known.", "nullable": true, "type": "string" }, "mbid": { "title": "Mbid", "description": "MusicBrainz Recording ID for the matched recording.", "nullable": true, "type": "string" }, "isrc": { "title": "Isrc", "description": "ISRC, when resolvable from the matched recording.", "nullable": true, "type": "string" }, "track_name": { "title": "Track Name", "description": "Track title from the AcoustID/MusicBrainz match.", "nullable": true, "type": "string" }, "artist_name": { "title": "Artist Name", "description": "Artist name(s) from the AcoustID/MusicBrainz match.", "nullable": true, "type": "string" }, "in_catalog": { "type": "boolean", "title": "In Catalog", "description": "True if the matched recording is already in the FreqBlog catalog. When true, `audio_features` is populated.", "default": false }, "audio_features": { "description": "Full FreqBlog audio features for the matched recording — populated when the MBID resolves to a catalog row, otherwise null. Call `/lookup` separately if you want to trigger an on-demand analysis for unknown recordings.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TrackLookupResponse" } ] }, "fingerprint_duration_seconds": { "title": "Fingerprint Duration Seconds", "description": "Duration of the fingerprinted audio (seconds), as reported by Chromaprint.", "nullable": true, "type": "number" } }, "type": "object", "required": [ "matched", "score" ], "title": "IdentifyResponse" }, "KeySearchResponse": { "properties": { "key": { "type": "string", "title": "Key", "description": "Resolved key in stored format, e.g. 'A-Minor'." }, "camelot": { "title": "Camelot", "description": "Camelot notation for this key.", "nullable": true, "type": "string" }, "open_key": { "title": "Open Key", "description": "Open Key notation for this key.", "nullable": true, "type": "string" }, "count": { "type": "integer", "title": "Count", "description": "Number of tracks returned." }, "tracks": { "items": { "$ref": "#/components/schemas/TrackLookupResponse" }, "type": "array", "title": "Tracks" } }, "type": "object", "required": [ "key", "count", "tracks" ], "title": "KeySearchResponse" }, "KeyVariant": { "properties": { "camelot": { "type": "string", "title": "Camelot", "description": "Camelot notation, e.g. `8A`.", "example": "8A" }, "open_key": { "title": "Open Key", "description": "Open Key notation, e.g. `1m`.", "nullable": true, "type": "string", "example": "1m" }, "key": { "type": "string", "title": "Key", "description": "Human-readable key, e.g. `A-Minor`.", "example": "A-Minor" }, "relation": { "type": "string", "title": "Relation", "description": "How this key relates to the input. One of: `same` (same key), `relative` (same number, opposite letter — minor↔major), `adjacent_up` (one step clockwise on the wheel), `adjacent_down` (one step counterclockwise), `energy_boost` (+7 same letter — common DJ key change up), `energy_drop` (-7 same letter — key change down).", "example": "adjacent_up" } }, "type": "object", "required": [ "camelot", "key", "relation" ], "title": "KeyVariant", "description": "One harmonically compatible key, returned by `/key/{camelot}/compatible`." }, "RadioResponse": { "properties": { "seed": { "$ref": "#/components/schemas/TrackStub" }, "count": { "type": "integer", "title": "Count" }, "constraints": { "type": "object", "title": "Constraints", "description": "Constraints applied to the walk: target BPM range, key adjacency depth, min similarity score." }, "tracks": { "items": { "$ref": "#/components/schemas/TrackStub" }, "type": "array", "title": "Tracks", "description": "Playlist in play order. Index 0 = seed, last index = closing track." } }, "type": "object", "required": [ "seed", "count", "constraints", "tracks" ], "title": "RadioResponse" }, "TransitionComponents": { "properties": { "harmonic": { "type": "integer", "maximum": 100, "minimum": 0, "title": "Harmonic", "description": "Key compatibility (Camelot wheel relationship), 0-100.", "example": 90 }, "tempo": { "type": "integer", "maximum": 100, "minimum": 0, "title": "Tempo", "description": "BPM compatibility — octave-aware (half/double time counts as a match), 0-100.", "example": 95 }, "energy": { "type": "integer", "maximum": 100, "minimum": 0, "title": "Energy", "description": "Smoothness of the energy step between the two tracks, 0-100.", "example": 88 } }, "type": "object", "required": [ "harmonic", "tempo", "energy" ], "title": "TransitionComponents", "description": "The three 0-100 sub-scores behind an overall mix score." }, "TransitionDetail": { "properties": { "key_relation": { "type": "string", "title": "Key Relation", "description": "How the two keys relate on the Camelot wheel: `same`, `relative` (minor↔major, same root), `adjacent_up`/`adjacent_down` (±1 hop), `energy_boost`/`energy_drop` (±7 — a deliberate lift/drop), `incompatible` (a clash), or `unknown` (one track has no detected key).", "example": "adjacent_up" }, "from_camelot": { "title": "From Camelot", "nullable": true, "type": "string", "example": "8A" }, "to_camelot": { "title": "To Camelot", "nullable": true, "type": "string", "example": "9A" }, "from_bpm": { "title": "From Bpm", "nullable": true, "type": "number", "example": 126.0 }, "to_bpm": { "title": "To Bpm", "nullable": true, "type": "number", "example": 128.0 }, "bpm_delta": { "type": "number", "title": "Bpm Delta", "description": "Signed BPM difference (to − from) after octave matching.", "example": 2.0 }, "bpm_octave_matched": { "type": "boolean", "title": "Bpm Octave Matched", "description": "True if the destination was matched at half/double time (e.g. 70 BPM treated as 140 to beat-match)." }, "from_energy": { "title": "From Energy", "description": "Source energy, normalised [0,1].", "nullable": true, "type": "number", "example": 0.62 }, "to_energy": { "title": "To Energy", "description": "Destination energy, normalised [0,1].", "nullable": true, "type": "number", "example": 0.66 }, "energy_delta": { "type": "number", "title": "Energy Delta", "description": "Signed energy difference (to − from), [-1,1].", "example": 0.04 } }, "type": "object", "required": [ "key_relation", "bpm_delta", "bpm_octave_matched", "energy_delta" ], "title": "TransitionDetail", "description": "The raw values the score was computed from — surface them to build your own UI." }, "TransitionResponse": { "properties": { "from_track": { "allOf": [ { "$ref": "#/components/schemas/TrackStub" } ], "description": "The track you're mixing OUT of." }, "to_track": { "allOf": [ { "$ref": "#/components/schemas/TrackStub" } ], "description": "The track you're mixing INTO." }, "score": { "type": "integer", "maximum": 100, "minimum": 0, "title": "Score", "description": "Overall 0-100 mix compatibility (0.50·harmonic + 0.30·tempo + 0.20·energy).", "example": 92 }, "components": { "$ref": "#/components/schemas/TransitionComponents" }, "detail": { "$ref": "#/components/schemas/TransitionDetail" }, "reason": { "type": "string", "title": "Reason", "description": "Plain-English explanation of the score.", "example": "8A->9A +1 adjacent, 126->128 BPM (+2.0), energy +0.04" } }, "type": "object", "required": [ "from_track", "to_track", "score", "components", "detail", "reason" ], "title": "TransitionResponse", "description": "Pairwise mix-compatibility score between two catalog tracks." }, "NextTrackSuggestion": { "properties": { "track": { "$ref": "#/components/schemas/TrackStub" }, "score": { "type": "integer", "maximum": 100, "minimum": 0, "title": "Score", "description": "Overall mix-compatibility score from the seed into this track.", "example": 96 }, "components": { "$ref": "#/components/schemas/TransitionComponents" }, "reason": { "type": "string", "title": "Reason", "description": "Plain-English explanation of the score.", "example": "11B->11B same key, 118->117 BPM (-0.29), energy +0.12" } }, "type": "object", "required": [ "track", "score", "components", "reason" ], "title": "NextTrackSuggestion" }, "NextTrackResponse": { "properties": { "seed": { "allOf": [ { "$ref": "#/components/schemas/TrackStub" } ], "description": "The track you're mixing out of." }, "count": { "type": "integer", "title": "Count", "description": "Number of suggestions returned (≤ `n`)." }, "suggestions": { "items": { "$ref": "#/components/schemas/NextTrackSuggestion" }, "type": "array", "title": "Suggestions", "description": "Best-first by overall mix-compatibility score." } }, "type": "object", "required": [ "seed", "count", "suggestions" ], "title": "NextTrackResponse", "description": "Ranked next-track suggestions for a seed — the candidates that mix best." }, "SetlistRequest": { "properties": { "track_ids": { "items": { "type": "string" }, "type": "array", "maxItems": 100, "minItems": 2, "title": "Track Ids", "description": "Catalog `itunes_track_id`s to order. 2-100. Duplicates are collapsed." }, "arc": { "type": "string", "enum": [ "peak_time", "warmup", "cooldown", "flat" ], "default": "peak_time", "title": "Arc", "description": "Target energy shape: `peak_time` (build to a peak ~3/4 in, then ease), `warmup` (steady rise), `cooldown` (steady fall), `flat` (hold — order purely for smooth transitions)." }, "start_track_id": { "title": "Start Track Id", "description": "Optional fixed opener (must be one of `track_ids`); otherwise chosen to fit the arc.", "nullable": true, "type": "string" } }, "type": "object", "required": [ "track_ids" ], "title": "SetlistRequest", "description": "Order a crate of tracks into a beat-matched, energy-arced set." }, "SetlistStep": { "properties": { "from_index": { "type": "integer", "title": "From Index", "description": "Index in `tracks` of the outgoing track." }, "to_index": { "type": "integer", "title": "To Index", "description": "Index in `tracks` of the incoming track." }, "score": { "type": "integer", "maximum": 100, "minimum": 0, "title": "Score", "description": "Transition score for this step." }, "reason": { "type": "string", "title": "Reason", "description": "Plain-English explanation of this step's transition." } }, "type": "object", "required": [ "from_index", "to_index", "score", "reason" ], "title": "SetlistStep" }, "SetlistResponse": { "properties": { "arc": { "type": "string", "title": "Arc", "description": "The arc shape that was applied.", "example": "peak_time" }, "count": { "type": "integer", "title": "Count", "description": "Number of tracks placed in the set." }, "flow_score": { "type": "integer", "maximum": 100, "minimum": 0, "title": "Flow Score", "description": "Mean transition score across the whole set — how smoothly it mixes.", "example": 91 }, "tracks": { "items": { "$ref": "#/components/schemas/TrackStub" }, "type": "array", "title": "Tracks", "description": "Tracks in play order. Index 0 = opener." }, "transitions": { "items": { "$ref": "#/components/schemas/SetlistStep" }, "type": "array", "title": "Transitions", "description": "Per-step transition scores, one per consecutive pair." }, "omitted": { "items": { "type": "string" }, "type": "array", "title": "Omitted", "description": "Requested ids not found in the catalog (skipped)." } }, "type": "object", "required": [ "arc", "count", "flow_score", "tracks", "transitions", "omitted" ], "title": "SetlistResponse", "description": "A crate ordered into a continuous, beat-matched, energy-arced set." }, "SearchResponse": { "properties": { "q": { "type": "string", "title": "Q", "description": "The query string as submitted." }, "count": { "type": "integer", "title": "Count", "description": "Number of tracks returned (≤ `limit`)." }, "results": { "items": { "$ref": "#/components/schemas/TrackStub" }, "type": "array", "title": "Results", "description": "Track stubs ordered by full-text relevance, then popularity descending." } }, "type": "object", "required": [ "q", "count", "results" ], "title": "SearchResponse" }, "SimilarResponse": { "properties": { "seed": { "$ref": "#/components/schemas/TrackStub", "description": "The seed track the recommendations are based on." }, "count": { "type": "integer", "title": "Count", "description": "Number of similar tracks returned (≤ `limit`)." }, "results": { "items": { "$ref": "#/components/schemas/SimilarTrackResult" }, "type": "array", "title": "Results", "description": "Tracks ordered by descending cosine similarity to the seed." } }, "type": "object", "required": [ "seed", "count", "results" ], "title": "SimilarResponse" }, "SimilarTrackResult": { "properties": { "track": { "$ref": "#/components/schemas/TrackStub" }, "score": { "type": "number", "title": "Score", "description": "Cosine similarity in [-1, 1]. Typically [0, 1] in practice. 1.0 = effectively identical features; 0.0 = orthogonal; negative = anti-correlated.", "example": 0.94 } }, "type": "object", "required": [ "track", "score" ], "title": "SimilarTrackResult" }, "TrackLookupResponse": { "properties": { "track_name": { "type": "string", "title": "Track Name", "description": "Track name as indexed from Apple Music charts or MusicBrainz.", "example": "Blinding Lights" }, "artist_name": { "type": "string", "title": "Artist Name", "description": "Artist name.", "example": "The Weeknd" }, "album_name": { "title": "Album Name", "description": "Album or single title. Populated for catalog tracks (Apple Music / iTunes source).", "nullable": true, "type": "string", "example": "After Hours" }, "itunes_track_id": { "type": "string", "title": "Itunes Track Id", "description": "iTunes track ID for catalog tracks; 'mb:{mbid}' for AcousticBrainz-sourced tracks; 'fma:{hash}' for FMA-sourced tracks; 'msd:{hash}' for Million Song Dataset tracks.", "example": "1488408568" }, "isrc": { "title": "Isrc", "description": "International Standard Recording Code. Uniquely identifies this specific master recording.", "nullable": true, "type": "string", "example": "GBAYE0601498" }, "mbid": { "title": "Mbid", "description": "MusicBrainz Recording ID (UUID). Cross-reference to the open music encyclopedia.", "nullable": true, "type": "string", "example": "5b11f4ce-a62d-471e-81fc-a69a8278c7da" }, "is_remix": { "title": "Is Remix", "description": "True when this recording is a third-party remix/bootleg (parsed from the title). False for originals and same-performance versions. `/lookup` only.", "type": "boolean", "example": true }, "remixer": { "title": "Remixer", "description": "The third-party artist credited with the remix, when attributable; null otherwise. `/lookup` only.", "nullable": true, "type": "string", "example": "Alesso" }, "mix_name": { "title": "Mix Name", "description": "Version/mix descriptor from the title (e.g. 'Extended Mix', 'Alesso Remix'). Null for a plain original. `/lookup` only.", "nullable": true, "type": "string", "example": "Extended Mix" }, "remix_of_isrc": { "title": "Remix Of Isrc", "description": "ISRC of the ORIGINAL recording this remix is based on, when the original is in the catalog. Lets you jump from a remix to its source. Null otherwise. `/lookup` only.", "nullable": true, "type": "string", "example": "USUM71116097" }, "release_date": { "title": "Release Date", "description": "Release date in ISO 8601 format (YYYY-MM-DD). Sourced from iTunes. Null for fallback-layer tracks.", "nullable": true, "type": "string", "example": "2020-03-20" }, "duration_ms": { "title": "Duration Ms", "description": "Full track duration in milliseconds from the iTunes catalog. Distinct from `duration_seconds` (which is the analysed 30s window).", "nullable": true, "type": "integer", "example": 200040 }, "explicit": { "title": "Explicit", "description": "True if the track is marked explicit by the source. Null when not reported.", "nullable": true, "type": "boolean", "example": false }, "source": { "title": "Source", "description": "Ingest source that first added this track, e.g. `apple_chart`, `deezer_chart`, `itunes_search`, `lastfm`, `jamendo`, `discovery_graph`.", "nullable": true, "type": "string", "example": "apple_chart" }, "first_ingested_at": { "title": "First Ingested At", "description": "ISO 8601 UTC timestamp of when this track was first added to the catalog.", "nullable": true, "type": "string", "example": "2025-11-14T01:23:45" }, "bpm": { "type": "number", "maximum": 300.0, "minimum": 20.0, "title": "Bpm", "description": "Tempo in beats per minute.", "example": 171.0 }, "bpm_alt": { "title": "Bpm Alt", "description": "Half-time/double-time corrected alternative BPM, when our heuristic suggests Essentia locked onto the wrong beat grid. Null when no correction is warranted. **Never** replaces `bpm` — use this when your downstream tooling expects the perceived rather than detected tempo (e.g. pop tracks like 'Blinding Lights' where Essentia returns ~85 but the perceived BPM is ~171).", "nullable": true, "type": "number", "example": 170.78 }, "bpm_confidence": { "title": "Bpm Confidence", "description": "Beat-strength score from Essentia RhythmExtractor2013. Null for AcousticBrainz-sourced tracks.", "nullable": true, "type": "number", "example": 3.8 }, "key": { "type": "string", "title": "Key", "description": "Musical key and scale, e.g. `C#-Minor`.", "example": "C#-Minor" }, "key_confidence": { "title": "Key Confidence", "description": "Key detection confidence [0–1]. Null for AcousticBrainz-sourced tracks.", "nullable": true, "type": "number", "maximum": 1.0, "minimum": 0.0, "example": 0.76 }, "mode": { "title": "Mode", "description": "Spotify-compatible mode integer: 0 = minor, 1 = major.", "nullable": true, "type": "integer", "maximum": 1.0, "minimum": 0.0, "example": 0 }, "key_int": { "title": "Key Int", "description": "Spotify-compatible pitch-class integer for the key: 0 = C, 1 = C♯/D♭, 2 = D, … 11 = B. `null` when the key is undetected/atonal (the Spotify-shaped `/v1/audio-features/{id}` endpoint reports `-1` in that case, matching Spotify's convention).", "nullable": true, "type": "integer", "maximum": 11.0, "minimum": 0.0, "example": 1 }, "camelot": { "title": "Camelot", "description": "Camelot wheel notation, e.g. `12A`.", "nullable": true, "type": "string", "example": "12A" }, "open_key": { "title": "Open Key", "description": "Open Key notation, e.g. `5m` (C#-Minor). d=major, m=minor.", "nullable": true, "type": "string", "example": "5m" }, "energy": { "title": "Energy", "description": "Normalised RMS energy [0–1]. Equivalent to Spotify's `energy` field.", "nullable": true, "type": "number", "maximum": 1.0, "minimum": 0.0, "example": 0.91 }, "loudness_db": { "title": "Loudness Db", "description": "Integrated loudness in dBFS.", "nullable": true, "type": "number", "example": -7.4 }, "danceability": { "title": "Danceability", "description": "Danceability score [0–1].", "nullable": true, "type": "number", "maximum": 1.0, "minimum": 0.0, "example": 0.78 }, "valence": { "title": "Valence", "description": "Musical positiveness [0–1].", "nullable": true, "type": "number", "maximum": 1.0, "minimum": 0.0, "example": 0.54 }, "speechiness": { "title": "Speechiness", "description": "Spoken word presence [0–1].", "nullable": true, "type": "number", "maximum": 1.0, "minimum": 0.0, "example": 0.06 }, "instrumentalness": { "title": "Instrumentalness", "description": "Instrumental likelihood [0–1].", "nullable": true, "type": "number", "maximum": 1.0, "minimum": 0.0, "example": 0.04 }, "liveness": { "title": "Liveness", "description": "Live performance likelihood [0–1].", "nullable": true, "type": "number", "maximum": 1.0, "minimum": 0.0, "example": 0.09 }, "acousticness": { "title": "Acousticness", "description": "Acoustic confidence [0–1].", "nullable": true, "type": "number", "maximum": 1.0, "minimum": 0.0, "example": 0.21 }, "time_signature": { "title": "Time Signature", "description": "Estimated time signature (3, 4, 5, etc.).", "nullable": true, "type": "integer", "example": 4 }, "mood": { "title": "Mood", "description": "MIREX-style mood category: happy, calm, sad, tense, energetic, melancholic, or neutral.", "nullable": true, "type": "string", "example": "happy" }, "mood_vector": { "title": "Mood Vector", "description": "Dimensional mood scores [0–1] across five axes: `happy`, `sad`, `aggressive`, `relaxed`, `party`. Populated when an AcousticBrainz high-level match is found; `null` otherwise.", "nullable": true, "additionalProperties": { "type": "number" }, "type": "object", "example": { "aggressive": 0.12, "happy": 0.82, "party": 0.77, "relaxed": 0.31, "sad": 0.04 } }, "representative_segment_start": { "title": "Representative Segment Start", "description": "Start time (seconds) of the highest-energy 30s window. 0.0 for 30s previews.", "nullable": true, "type": "number", "example": 0.0 }, "onset_rate": { "title": "Onset Rate", "description": "Onset events per second from AcousticBrainz low-level analysis. Higher values indicate more rhythmic or percussive content. Populated when an AcousticBrainz match is found; `null` otherwise.", "nullable": true, "type": "number", "example": 2.86 }, "dynamic_complexity": { "title": "Dynamic Complexity", "description": "Loudness variation over the track (dB), from AcousticBrainz low-level analysis. Higher values mean wider dynamic range; lower values mean more compressed mastering. Populated when an AcousticBrainz match is found; `null` otherwise.", "nullable": true, "type": "number", "example": 5.61 }, "tuning_frequency": { "title": "Tuning Frequency", "description": "Estimated A4 reference frequency in Hz, from AcousticBrainz tonal analysis. Modern recordings cluster near 440 Hz; older or non-Western recordings may diverge. Populated when an AcousticBrainz match is found; `null` otherwise.", "nullable": true, "type": "number", "example": 440.0 }, "average_loudness": { "title": "Average Loudness", "description": "Average loudness as a normalised value [0–1] from AcousticBrainz low-level analysis. Distinct from `loudness_db` (which is dBFS from this service's own analysis). Populated when an AcousticBrainz match is found; `null` otherwise.", "nullable": true, "type": "number", "example": 0.703 }, "genre": { "title": "Genre", "description": "Broad genre classification (e.g. electronic, rock, pop, hip-hop, jazz). Sourced from AcousticBrainz or Last.fm.", "nullable": true, "type": "string", "example": "electronic" }, "extended": { "description": "Higher-level AcousticBrainz classifications. Populated when the track has an AcousticBrainz match — null otherwise. **Not counted toward the 38-field headline** because each value is a categorical label, not an analysis field.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ExtendedAudioFeatures" } ] }, "feature_source": { "title": "Feature Source", "description": "Provenance of the audio feature data. One of: `essentia_preview` (analysed from a 30s preview by this service), `acousticbrainz` (matched by MBID against the AcousticBrainz dump), `fma` (FMA Echo Nest dataset), `msd` (Million Song Dataset), `user_upload` (analysed from a file the user uploaded).", "nullable": true, "type": "string", "example": "essentia_preview" }, "backfill_status": { "title": "Backfill Status", "description": "Backfill job status if one was queued: 'queued', 'processing', 'completed', 'failed'. Null if no backfill was needed.", "nullable": true, "type": "string", "example": "queued" }, "backfill_notification_id": { "title": "Backfill Notification Id", "description": "Notification ID for tracking backfill progress. Use to query backfill_notifications table.", "nullable": true, "type": "string", "example": "backfill_1488408568_1713950025" } }, "type": "object", "required": [ "track_name", "artist_name", "itunes_track_id", "bpm", "key" ], "title": "TrackLookupResponse" }, "TrackStub": { "properties": { "itunes_track_id": { "type": "string", "title": "Itunes Track Id", "description": "Track id (catalog `itunes_track_id` or synthetic prefix). Pass to `/track/{id}/embedding` or use the name+artist with `/lookup`.", "example": "1488408568" }, "track_name": { "type": "string", "title": "Track Name", "example": "Blinding Lights" }, "artist_name": { "type": "string", "title": "Artist Name", "example": "The Weeknd" }, "album_name": { "title": "Album Name", "nullable": true, "type": "string", "example": "After Hours" }, "popularity": { "type": "integer", "title": "Popularity", "description": "Internal popularity score (higher = more popular). Used for default ordering.", "default": 0 }, "mbid": { "title": "Mbid", "description": "MusicBrainz Recording ID, when known.", "nullable": true, "type": "string" }, "isrc": { "title": "Isrc", "description": "ISRC, when known.", "nullable": true, "type": "string" }, "genre": { "title": "Genre", "description": "Broad genre classification, when known.", "nullable": true, "type": "string" }, "release_date": { "title": "Release Date", "description": "ISO 8601 release date, when known.", "nullable": true, "type": "string", "example": "2019-11-29" }, "duration_ms": { "title": "Duration Ms", "nullable": true, "type": "integer", "example": 200040 }, "explicit": { "title": "Explicit", "nullable": true, "type": "boolean" }, "source": { "title": "Source", "description": "Ingest source identifier, e.g. `apple_chart`, `itunes_search`, `lastfm`.", "nullable": true, "type": "string" } }, "type": "object", "required": [ "itunes_track_id", "track_name", "artist_name" ], "title": "TrackStub", "description": "Minimal track shape for search and browse endpoints. No audio features.\nUse `/lookup` for full audio features once you have a track id." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "WebhookConfig": { "properties": { "url": { "type": "string", "maxLength": 500, "minLength": 8, "title": "Url", "description": "HTTPS URL where backfill notifications will be POSTed.", "example": "https://example.com/freqblog-webhook" } }, "type": "object", "required": [ "url" ], "title": "WebhookConfig" }, "WebhookStatus": { "properties": { "url": { "title": "Url", "description": "Current webhook URL, or null if none configured.", "nullable": true, "type": "string" }, "signing_note": { "type": "string", "title": "Signing Note", "description": "How to verify webhook authenticity.", "default": "Each POST is signed with X-FreqBlog-Signature: sha256=<hex>, computed as HMAC-SHA256(sha256(your_api_key_plaintext), request_body). Verify on your end to confirm the request came from FreqBlog." } }, "type": "object", "title": "WebhookStatus" }, "RecommendationSeed": { "properties": { "id": { "type": "string", "title": "Id", "description": "Seed track id as supplied.", "example": "apple_ad1829eeccb70f9a" }, "found": { "type": "boolean", "title": "Found", "description": "True if the seed was usable (in the catalog with enough audio features)." } }, "type": "object", "required": [ "id", "found" ], "title": "RecommendationSeed" }, "RecommendationsResponse": { "properties": { "seeds": { "items": { "$ref": "#/components/schemas/RecommendationSeed" }, "type": "array", "title": "Seeds", "description": "Echo of the supplied seeds with a found/unfound flag." }, "seed_query": { "description": "When seeded by name (`track`/`artist`) instead of an id, the catalogue track that name resolved to — so you can confirm the right track was picked. Null when seeding by `seed_tracks`.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TrackStub" } ], "title": "Seed Query" }, "count": { "type": "integer", "title": "Count", "description": "Number of recommended tracks returned (≤ `limit`)." }, "tracks": { "items": { "$ref": "#/components/schemas/SimilarTrackResult" }, "type": "array", "title": "Tracks", "description": "Recommended tracks ordered by genre-aware relevance to the seed blend. `score` is the raw audio-feature cosine similarity (genre affinity influences ordering, not the score), so it may not be strictly descending." } }, "type": "object", "required": [ "seeds", "count", "tracks" ], "title": "RecommendationsResponse", "description": "Spotify-shaped recommendations: blend up to 5 seed tracks and return the nearest catalogue tracks by audio-feature similarity, re-ranked by genre affinity. Drop-in for the removed Spotify GET /v1/recommendations — FreqBlog catalog ids, open-data ranking." }, "RelatedArtist": { "properties": { "artist_name": { "type": "string", "title": "Artist Name", "example": "AC/DC" }, "score": { "type": "number", "title": "Score", "description": "Aggregate similarity of this artist's tracks to the seed artist (higher = closer).", "example": 0.93 }, "match_count": { "type": "integer", "title": "Match Count", "description": "How many of this artist's tracks fell in the seed artist's neighbourhood." }, "sample_track_id": { "title": "Sample Track Id", "description": "A representative catalog track id by this artist — pass to `/lookup` or `/next-track`.", "nullable": true, "type": "string", "example": "apple_ad1829eeccb70f9a" } }, "type": "object", "required": [ "artist_name", "score", "match_count" ], "title": "RelatedArtist" }, "RelatedArtistsResponse": { "properties": { "artist": { "type": "string", "title": "Artist", "description": "The seed artist as supplied.", "example": "Van Halen" }, "count": { "type": "integer", "title": "Count", "description": "Number of related artists returned (≤ `limit`)." }, "related": { "items": { "$ref": "#/components/schemas/RelatedArtist" }, "type": "array", "title": "Related", "description": "Related artists, best-first." } }, "type": "object", "required": [ "artist", "count", "related" ], "title": "RelatedArtistsResponse", "description": "Spotify-shaped related-artists: artists who make tracks similar to the seed artist's. Drop-in for the removed Spotify /v1/artists/{id}/related-artists." }, "TagItem": { "type": "object", "title": "TagItem", "required": [ "tag", "category", "confidence", "provenance" ], "properties": { "tag": { "type": "string", "title": "Tag", "description": "Human-readable tag, e.g. `high-energy`, `acoustic`, `party`, `synthwave`.", "example": "high-energy" }, "category": { "type": "string", "title": "Category", "description": "energy | danceability | valence | acousticness | instrumentalness | mood | genre.", "example": "energy" }, "value": { "type": "number", "nullable": true, "title": "Value", "description": "Underlying [0,1] score for numeric tags; null for label-only tags (mood category, genre).", "example": 0.91 }, "confidence": { "type": "string", "title": "Confidence", "description": "measured | derived | model-estimated | catalog-genre.", "example": "measured" }, "provenance": { "type": "string", "title": "Provenance", "description": "essentia | valence+energy | acousticbrainz | catalog.", "example": "essentia" } } }, "TagResponse": { "type": "object", "title": "TagResponse", "required": [ "track", "count", "tags", "disclaimer" ], "properties": { "track": { "$ref": "#/components/schemas/TrackStub" }, "count": { "type": "integer", "title": "Count", "description": "Number of tags returned." }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/TagItem" }, "title": "Tags", "description": "Tags, each with a confidence + provenance so you can judge reliability." }, "disclaimer": { "type": "string", "title": "Disclaimer", "description": "How to read the confidence levels." } } } } }, "tags": [ { "name": "Catalog" }, { "name": "Spotify-compat" } ] } </article></body></html>