{ "openapi": "3.1.0", "info": { "title": "SonoVault API", "version": "1.0.0", "description": "Music metadata API — search tracks, resolve ISRCs and cross-platform IDs, and browse artists, labels, and releases. This spec is generated from the SonoVault docs source of truth; the rendered docs at https://sonovault.now/docs are authoritative if anything diverges." }, "servers": [ { "url": "https://api.sonovault.now" } ], "tags": [ { "name": "Tracks" }, { "name": "Artists" }, { "name": "Labels" }, { "name": "Releases" }, { "name": "Genres" }, { "name": "Suggestions" } ], "security": [ { "ApiKeyAuth": [] } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Your SonoVault API key. Get one at https://sonovault.now." } } }, "paths": { "/v1/tracks/search": { "get": { "operationId": "track-search", "summary": "Track search", "description": "Search for tracks by artist and title. Returns ISRC, genre, release dates, and full metadata.", "tags": [ "Tracks" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "artist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "label": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "release_date": { "type": "string" } } } }, "artists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_primary": { "type": "boolean" }, "is_remixer": { "type": "boolean" } } } }, "isrc": { "type": "string" }, "duration": { "type": "integer" }, "genre": { "type": "array", "items": { "type": "string" } }, "subgenre": { "type": "array", "items": { "type": "string" } } } } }, "next_cursor": { "type": "string" } } }, "example": { "results": [ { "id": 123, "title": "One More Time", "releases": [ { "id": 1, "title": "Discovery", "artist": { "id": 1, "name": "Daft Punk" }, "label": { "id": 10, "name": "Virgin Records" }, "release_date": "2001-03-12" } ], "artists": [ { "id": 1, "name": "Daft Punk", "is_primary": true, "is_remixer": false } ], "isrc": "GBDUW0000053", "duration": 320, "genre": [ "House" ], "subgenre": [ "French House" ] } ], "next_cursor": "eyJpZCI6MTIzfQ" } } } } }, "parameters": [ { "name": "artist", "in": "query", "required": true, "description": "Artist name.", "schema": { "type": "string" } }, { "name": "title", "in": "query", "required": true, "description": "Track title.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max results, 1–100. Default 20.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from previous response for pagination.", "schema": { "type": "string" } } ] } }, "/v1/tracks/isrc/{isrc}": { "get": { "operationId": "isrc-lookup", "summary": "ISRC lookup", "description": "Exact lookup by ISRC code. The ISRC is part of the path — there is no query string. Returns full track detail including genre and subgenre.", "tags": [ "Tracks" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "artist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "label": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "release_date": { "type": "string" } } } }, "artists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_primary": { "type": "boolean" }, "is_remixer": { "type": "boolean" } } } }, "isrc": { "type": "string" }, "duration": { "type": "integer" }, "genre": { "type": "array", "items": { "type": "string" } }, "subgenre": { "type": "array", "items": { "type": "string" } } } }, "example": { "id": 123, "title": "One More Time", "releases": [ { "id": 1, "title": "Discovery", "artist": { "id": 1, "name": "Daft Punk" }, "label": { "id": 10, "name": "Virgin Records" }, "release_date": "2001-03-12" } ], "artists": [ { "id": 1, "name": "Daft Punk", "is_primary": true, "is_remixer": false } ], "isrc": "GBDUW0000053", "duration": 320, "genre": [ "House" ], "subgenre": [ "French House" ] } } } } }, "parameters": [ { "name": "isrc", "in": "path", "required": true, "description": "ISRC code (e.g. GBDUW0000053).", "schema": { "type": "string" } } ] } }, "/v1/tracks/{id}": { "get": { "operationId": "track-by-id", "summary": "Track by ID", "description": "Get a single track by its internal SonoVault track ID. Returns the same track payload as ISRC lookup — title, artists, releases, ISRC, duration, genre, and subgenre.", "tags": [ "Tracks" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "artist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "label": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "release_date": { "type": "string" } } } }, "artists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_primary": { "type": "boolean" }, "is_remixer": { "type": "boolean" } } } }, "isrc": { "type": "string" }, "duration": { "type": "integer" }, "genre": { "type": "array", "items": { "type": "string" } }, "subgenre": { "type": "array", "items": { "type": "string" } } } }, "example": { "id": 123, "title": "One More Time", "releases": [ { "id": 1, "title": "Discovery", "artist": { "id": 1, "name": "Daft Punk" }, "label": { "id": 10, "name": "Virgin Records" }, "release_date": "2001-03-12" } ], "artists": [ { "id": 1, "name": "Daft Punk", "is_primary": true, "is_remixer": false } ], "isrc": "GBDUW0000053", "duration": 320, "genre": [ "House" ], "subgenre": [ "French House" ] } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Internal SonoVault track ID.", "schema": { "type": "integer" } } ] } }, "/v1/tracks/links": { "get": { "operationId": "platform-links", "summary": "Platform links", "description": "Lightweight cross-platform ID resolver. Given an ISRC or a source-specific ID, returns all known external platform links.", "tags": [ "Tracks" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "track_id": { "type": "integer" }, "title": { "type": "string" }, "isrc": { "type": "string" }, "links": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "external_id": { "type": "string" }, "url": { "type": "string" } } } } } }, "example": { "track_id": 123, "title": "One More Time", "isrc": "GBDUW0000053", "links": [ { "source": "spotify", "external_id": "5sICkBXVmaCQk5aISGR3x0", "url": "https://open.spotify.com/track/5sICkBXVmaCQk5aISGR3x0" }, { "source": "beatport", "external_id": "12345678", "url": "https://www.beatport.com/track/-/12345678" }, { "source": "applemusic", "external_id": "1440650", "url": "https://music.apple.com/song/1440650" }, { "source": "tidal", "external_id": "3789025", "url": "https://tidal.com/browse/track/3789025" } ] } } } } }, "parameters": [ { "name": "id", "in": "query", "required": false, "description": "Internal SonoVault track ID. Provide one lookup param at a time.", "schema": { "type": "integer" } }, { "name": "isrc", "in": "query", "required": false, "description": "ISRC code.", "schema": { "type": "string" } }, { "name": "spotify_id", "in": "query", "required": false, "description": "Spotify track ID.", "schema": { "type": "string" } }, { "name": "beatport_id", "in": "query", "required": false, "description": "Beatport track ID.", "schema": { "type": "string" } }, { "name": "discogs_id", "in": "query", "required": false, "description": "Discogs release ID.", "schema": { "type": "string" } }, { "name": "musicbrainz_id", "in": "query", "required": false, "description": "MusicBrainz recording ID.", "schema": { "type": "string" } }, { "name": "applemusic_id", "in": "query", "required": false, "description": "Apple Music track ID.", "schema": { "type": "string" } }, { "name": "tidal_id", "in": "query", "required": false, "description": "Tidal track ID.", "schema": { "type": "string" } } ] } }, "/v1/tracks/resolve": { "post": { "operationId": "bulk-resolve", "summary": "Bulk resolve", "description": "Resolve up to 100 inputs in a single request — track names, ISRCs, or platform IDs — to canonical SonoVault tracks plus their cross-platform links. One credit is charged per input line. If your monthly quota runs out mid-batch the response is partial: unresolved lines come back with status `skipped_no_credits` instead of an error.\n\n**Response**\n\n- `results` — one entry per input line, in input order: `{ input, status, track, links }`, where `status` is `matched`, `not_found`, or `skipped_no_credits`.\n\n- `partial`, `processed`, `credits_used`, `credits_remaining`, `message` — the batch billing summary.", "tags": [ "Tracks" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "input": { "type": "string" }, "status": { "type": "string" }, "track": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "artist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "label": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "release_date": { "type": "string" } } } }, "artists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_primary": { "type": "boolean" }, "is_remixer": { "type": "boolean" } } } }, "isrc": { "type": "string" }, "duration": { "type": "integer" }, "genre": { "type": "array", "items": { "type": "string" } }, "subgenre": { "type": "array", "items": { "type": "string" } } } }, "links": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "external_id": { "type": "string" }, "url": { "type": "string" } } } } } } }, "partial": { "type": "boolean" }, "processed": { "type": "integer" }, "credits_used": { "type": "integer" }, "credits_remaining": { "type": "integer" }, "message": {} } }, "example": { "results": [ { "input": "GBDUW0000053", "status": "matched", "track": { "id": 123, "title": "One More Time", "releases": [ { "id": 1, "title": "Discovery", "artist": { "id": 1, "name": "Daft Punk" }, "label": { "id": 10, "name": "Virgin Records" }, "release_date": "2001-03-12" } ], "artists": [ { "id": 1, "name": "Daft Punk", "is_primary": true, "is_remixer": false } ], "isrc": "GBDUW0000053", "duration": 320, "genre": [ "House" ], "subgenre": [ "French House" ] }, "links": [ { "source": "spotify", "external_id": "5sICkBXVmaCQk5aISGR3x0", "url": "https://open.spotify.com/track/5sICkBXVmaCQk5aISGR3x0" } ] }, { "input": "USQX91300108", "status": "not_found", "track": null, "links": [] } ], "partial": false, "processed": 2, "credits_used": 2, "credits_remaining": 968, "message": null } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input_type": { "type": "string", "description": "one of `track_name`, `isrc`, `sonovault_id`, `spotify_id`, `applemusic_id`, `tidal_id`, `beatport_id`, `discogs_id`, `musicbrainz_id`." }, "items": { "type": "string", "description": "1 to 100 entries. For `track_name`, each entry is an object `{ artist, title }`; for every other input type, each entry is a string." } }, "required": [ "input_type", "items" ] } } } } } }, "/v1/artists/search": { "get": { "operationId": "artist-search", "summary": "Artist search", "description": "Search for artists by name. Returns each artist with country, formation year (and full formation date when day-level precision is known), social links, and Wikidata ID where available.", "tags": [ "Artists" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "country": { "type": "string" }, "formation_year": { "type": "integer" }, "formation_date": {}, "social_links": { "type": "object", "properties": { "website": { "type": "string" }, "twitter": { "type": "string" }, "instagram": { "type": "string" }, "facebook": { "type": "string" } } }, "wikidata_id": { "type": "string" } } } }, "next_cursor": { "type": "string" } } }, "example": { "results": [ { "id": 1, "name": "Daft Punk", "country": "France", "formation_year": 1993, "formation_date": null, "social_links": { "website": "https://daftpunk.com/", "twitter": "daftpunk_music", "instagram": "daftpunk", "facebook": "100044021024570" }, "wikidata_id": "Q185828" } ], "next_cursor": "0:5000000:1" } } } } }, "parameters": [ { "name": "name", "in": "query", "required": true, "description": "Artist name to search.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max results, 1–100. Default 20.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from previous response for pagination.", "schema": { "type": "string" } } ] } }, "/v1/artists/{id}": { "get": { "operationId": "artist-by-id", "summary": "Artist by ID", "description": "Get artist by ID. Returns the public artist fields (country, formation_year + optional formation_date, social_links, wikidata_id) flattened alongside a release_count summary. For the actual release list, use /v1/artists/:id/releases — the embedded array was removed because it became huge for prolific artists.", "tags": [ "Artists" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "country": { "type": "string" }, "formation_year": { "type": "integer" }, "formation_date": {}, "social_links": { "type": "object", "properties": { "website": { "type": "string" }, "twitter": { "type": "string" }, "instagram": { "type": "string" }, "facebook": { "type": "string" } } }, "wikidata_id": { "type": "string" }, "release_count": { "type": "integer" } } }, "example": { "id": 1, "name": "Daft Punk", "country": "France", "formation_year": 1993, "formation_date": null, "social_links": { "website": "https://daftpunk.com/", "twitter": "daftpunk_music", "instagram": "daftpunk", "facebook": "100044021024570" }, "wikidata_id": "Q185828", "release_count": 14 } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Artist ID.", "schema": { "type": "integer" } } ] } }, "/v1/artists/{id}/releases": { "get": { "operationId": "artist-releases", "summary": "Releases by artist", "description": "Paginated feed of releases by a specific artist, ordered by release date (newest first). The per-item artist field is omitted (the caller already knows it).", "tags": [ "Releases" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "label": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "release_date": { "type": "string" }, "catalog_no": { "type": "string" }, "track_count": { "type": "integer" } } } }, "next_cursor": { "type": "string" } } }, "example": { "results": [ { "id": 1, "title": "Discovery", "label": { "id": 10, "name": "Virgin Records" }, "release_date": "2001-03-12", "catalog_no": "724384960650", "track_count": 14 } ], "next_cursor": "2001-03-12:1" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Artist ID.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Max results, 1–100. Default 20.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from previous response for pagination.", "schema": { "type": "string" } } ] } }, "/v1/labels/search": { "get": { "operationId": "label-search", "summary": "Label search", "description": "Search for record labels by name. Returns labels sorted by relevance and release count.", "tags": [ "Labels" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "release_count": { "type": "integer" } } } }, "next_cursor": { "type": "string" } } }, "example": { "results": [ { "id": 1, "name": "Drumcode", "release_count": 842 } ], "next_cursor": "0:842:1" } } } } }, "parameters": [ { "name": "name", "in": "query", "required": true, "description": "Label name to search.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max results, 1–100. Default 20.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from previous response for pagination.", "schema": { "type": "string" } } ] } }, "/v1/labels/{id}": { "get": { "operationId": "label-by-id", "summary": "Label by ID", "description": "Get label by ID. Returns the public label fields (id, name) flattened alongside release_count and artist_count summaries. For the actual lists, use /v1/labels/:id/releases and /v1/labels/:id/artists — embedded arrays were removed because they became huge for prolific labels.", "tags": [ "Labels" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "release_count": { "type": "integer" }, "artist_count": { "type": "integer" } } }, "example": { "id": 1, "name": "Drumcode", "release_count": 842, "artist_count": 67 } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Label ID.", "schema": { "type": "integer" } } ] } }, "/v1/labels/{id}/releases": { "get": { "operationId": "label-releases", "summary": "Releases by label", "description": "Paginated feed of releases on a specific label, ordered by release date (newest first). Each result carries the primary artist, label, catalog number, and track count.", "tags": [ "Releases" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "artist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "label": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "release_date": { "type": "string" }, "catalog_no": { "type": "string" }, "track_count": { "type": "integer" } } } }, "next_cursor": { "type": "string" } } }, "example": { "results": [ { "id": 10, "title": "Drumcode 01", "artist": { "id": 5, "name": "Adam Beyer" }, "label": { "id": 1, "name": "Drumcode" }, "release_date": "2024-03-15", "catalog_no": "DC001", "track_count": 8 } ], "next_cursor": "2024-03-15:10" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Label ID.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Max results, 1–100. Default 20.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from previous response for pagination.", "schema": { "type": "string" } } ] } }, "/v1/labels/{id}/artists": { "get": { "operationId": "label-artists", "summary": "Artists by label", "description": "Paginated list of artists with releases on a specific label, ordered by number of releases on that label (descending). Each artist carries the public profile fields and a release_count scoped to this label.", "tags": [ "Artists" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "country": { "type": "string" }, "formation_year": { "type": "integer" }, "formation_date": {}, "social_links": { "type": "object", "properties": { "website": { "type": "string" }, "twitter": { "type": "string" } } }, "wikidata_id": { "type": "string" }, "release_count": { "type": "integer" } } } }, "next_cursor": { "type": "string" } } }, "example": { "results": [ { "id": 5, "name": "Adam Beyer", "country": "Sweden", "formation_year": 1976, "formation_date": null, "social_links": { "website": "https://adambeyer.com", "twitter": "adam_beyer" }, "wikidata_id": "Q469843", "release_count": 42 } ], "next_cursor": "42:5" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Label ID.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Max results, 1–100. Default 20.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from previous response for pagination.", "schema": { "type": "string" } } ] } }, "/v1/releases/search": { "get": { "operationId": "release-search", "summary": "Release search", "description": "Search for releases by title, optionally filtered by artist.", "tags": [ "Releases" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "artist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "label": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "release_date": { "type": "string" } } } }, "next_cursor": { "type": "string" } } }, "example": { "results": [ { "id": 1, "title": "Discovery", "artist": { "id": 1, "name": "Daft Punk" }, "label": { "id": 10, "name": "Virgin Records" }, "release_date": "2001-03-12" } ], "next_cursor": "0:85:1" } } } } }, "parameters": [ { "name": "title", "in": "query", "required": true, "description": "Release title to search.", "schema": { "type": "string" } }, { "name": "artist", "in": "query", "required": false, "description": "Artist name filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max results, 1–100. Default 20.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from previous response for pagination.", "schema": { "type": "string" } } ] } }, "/v1/releases/{id}": { "get": { "operationId": "release-by-id", "summary": "Release by ID", "description": "Get release by ID. Returns the release fields flat with nested artist and label objects, plus a peer tracks[] array — each track has ISRC, genre, subgenre, and artist credits.", "tags": [ "Releases" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "artist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "label": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "release_date": { "type": "string" }, "catalog_no": { "type": "string" }, "tracks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "duration": { "type": "integer" }, "isrc": { "type": "string" }, "artists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_primary": { "type": "boolean" }, "is_remixer": { "type": "boolean" } } } }, "genre": { "type": "array", "items": { "type": "string" } }, "subgenre": { "type": "array", "items": { "type": "string" } } } } } } }, "example": { "id": 1, "title": "Discovery", "artist": { "id": 1, "name": "Daft Punk" }, "label": { "id": 10, "name": "Virgin Records" }, "release_date": "2001-03-12", "catalog_no": "724384960650", "tracks": [ { "id": 123, "title": "One More Time", "duration": 320, "isrc": "GBDUW0000053", "artists": [ { "id": 1, "name": "Daft Punk", "is_primary": true, "is_remixer": false } ], "genre": [ "House" ], "subgenre": [ "French House" ] } ] } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Release ID.", "schema": { "type": "integer" } } ] } }, "/v1/releases/new": { "get": { "operationId": "new-releases", "summary": "New releases", "description": "Paginated feed of releases ordered by release date (newest first).\n\n**Requires a paid plan** — the free tier returns `403` for this endpoint.", "tags": [ "Releases" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "artist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "label": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "release_date": { "type": "string" }, "track_count": { "type": "integer" } } } }, "next_cursor": { "type": "string" } } }, "example": { "results": [ { "id": 789, "title": "Resonance EP", "artist": { "id": 3, "name": "Bicep" }, "label": { "id": 42, "name": "Ninja Tune" }, "release_date": "2026-03-22", "track_count": 4 } ], "next_cursor": "2026-03-22:78:789" } } } } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "1–100. Default 20.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from previous response for pagination.", "schema": { "type": "string" } } ], "x-paid-plan": true } }, "/v1/tracks/browse": { "get": { "operationId": "track-browse", "summary": "Browse tracks", "description": "Discover tracks by filtering on label, artist, genre, or year. Returns up to 20 tracks ordered by release date (newest first) by default; pass `randomize=true` to sample 20 random tracks from the top-popularity pool instead. At least one filter parameter is required — calls with no filters return `400`. Filter by genre with either `genreId` (a canonical id from `GET /v1/genres`) or `genre` (a free-text exact name) — prefer `genreId` as it is stable and unambiguous; use `genre` only to reach rare subgenres that `/v1/genres` does not list. `genre` and `genreId` are mutually exclusive — passing both returns `400`.\n\n**Requires a paid plan** — the free tier returns `403` for this endpoint.", "tags": [ "Tracks" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "releases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "artist": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "label": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "release_date": { "type": "string" } } } }, "artists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_primary": { "type": "boolean" }, "is_remixer": { "type": "boolean" } } } }, "isrc": { "type": "string" }, "duration": { "type": "integer" }, "genre": { "type": "array", "items": { "type": "string" } }, "subgenre": { "type": "array", "items": { "type": "string" } } } } } } }, "example": { "results": [ { "id": 456, "title": "One More Time", "releases": [ { "id": 1, "title": "Discovery", "artist": { "id": 1, "name": "Daft Punk" }, "label": { "id": 10, "name": "Virgin Records" }, "release_date": "2001-03-12" } ], "artists": [ { "id": 1, "name": "Daft Punk", "is_primary": true, "is_remixer": false } ], "isrc": "GBDUW0000053", "duration": 320, "genre": [ "House" ], "subgenre": [ "French House" ] } ] } } } } }, "parameters": [ { "name": "labelId", "in": "query", "required": false, "description": "Filter by label ID.", "schema": { "type": "integer" } }, { "name": "artistId", "in": "query", "required": false, "description": "Filter by artist ID.", "schema": { "type": "integer" } }, { "name": "genre", "in": "query", "required": false, "description": "Exact genre name, case-insensitive (`House` matches House but not Tech House). Free-text alternative to `genreId` — use it for rare subgenres not listed by `GET /v1/genres`. Mutually exclusive with `genreId`.", "schema": { "type": "string" } }, { "name": "genreId", "in": "query", "required": false, "description": "Canonical genre id from `GET /v1/genres` — the stable, unambiguous way to filter by genre. Mutually exclusive with `genre`.", "schema": { "type": "integer" } }, { "name": "year", "in": "query", "required": false, "description": "Release year (e.g. 2025).", "schema": { "type": "integer" } }, { "name": "randomize", "in": "query", "required": false, "description": "If `true`, return 20 random tracks sampled from the top 1000 by popularity instead of the most recent releases. Defaults to `false`.", "schema": { "type": "boolean" } } ], "x-paid-plan": true } }, "/v1/genres": { "get": { "operationId": "genre-list", "summary": "List genres", "description": "Lists every canonical genre and subgenre SonoVault recognises. Use this to find the numeric `genreId` for a genre suggestion — the suggestion endpoint validates against this exact list, so it never goes out of date.", "tags": [ "Genres" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "genres": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" }, "parent": {} } } } } }, "example": { "genres": [ { "id": 12, "name": "House", "type": "main", "parent": null }, { "id": 47, "name": "French House", "type": "subgenre", "parent": "House" } ] } } } } } } }, "/v1/tracks/{id}/suggestions": { "post": { "operationId": "submit-suggestion", "summary": "Suggest a genre", "description": "Suggest a better genre for a track. Suggestions are reviewed by the SonoVault team before they affect the catalog — a successful call returns the suggestion with `status: \"pending\"`. Requires a paid plan.\n\n**Requires a paid plan** — the free tier returns `403` for this endpoint.\n\n**Limits**\n\n- Up to 100 suggestions per day per account. Can be increased upon request.", "tags": [ "Suggestions" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "track_id": { "type": "integer" }, "field": { "type": "string" }, "proposed_value": { "type": "object", "properties": { "genre_id": { "type": "integer" }, "genre_name": { "type": "string" } } }, "current_value": { "type": "object", "properties": { "genre": { "type": "array", "items": { "type": "string" } }, "subgenre": { "type": "array", "items": {} } } }, "note": { "type": "string" }, "status": { "type": "string" }, "review_note": {}, "created_at": { "type": "string" }, "reviewed_at": {} } }, "example": { "id": 5012, "track_id": 123, "field": "genre", "proposed_value": { "genre_id": 47, "genre_name": "French House" }, "current_value": { "genre": [ "Pop" ], "subgenre": [] }, "note": "This is clearly French House, not Pop.", "status": "pending", "review_note": null, "created_at": "2026-05-15T10:32:00.000Z", "reviewed_at": null } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Internal SonoVault track ID.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "genreId": { "type": "integer", "description": "a genre id from `GET /v1/genres`." }, "note": { "type": "string", "description": "a short explanation for the reviewer, max 100 characters." } }, "required": [ "genreId" ] } } } }, "x-paid-plan": true } }, "/v1/suggestions": { "get": { "operationId": "my-suggestions", "summary": "List your suggestions", "description": "Lists the edit suggestions you have submitted and their review status (`pending`, `approved`, or `rejected`), newest first.", "tags": [ "Suggestions" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "track_id": { "type": "integer" }, "field": { "type": "string" }, "proposed_value": { "type": "object", "properties": { "genre_id": { "type": "integer" }, "genre_name": { "type": "string" } } }, "current_value": { "type": "object", "properties": { "genre": { "type": "array", "items": { "type": "string" } }, "subgenre": { "type": "array", "items": {} } } }, "note": { "type": "string" }, "status": { "type": "string" }, "review_note": {}, "created_at": { "type": "string" }, "reviewed_at": { "type": "string" } } } }, "next_cursor": {} } }, "example": { "results": [ { "id": 5012, "track_id": 123, "field": "genre", "proposed_value": { "genre_id": 47, "genre_name": "French House" }, "current_value": { "genre": [ "Pop" ], "subgenre": [] }, "note": "This is clearly French House, not Pop.", "status": "approved", "review_note": null, "created_at": "2026-05-15T10:32:00.000Z", "reviewed_at": "2026-05-15T14:05:00.000Z" } ], "next_cursor": null } } } } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Max results, 1–100. Default 20.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from previous response for pagination.", "schema": { "type": "string" } } ] } } } }