--- title: "Release by ID" method: GET path: "/v1/releases/{id}" tags: ["Releases"] --- # Release by ID `GET /v1/releases/{id}` ## Request - Base URL: `https://api.sonovault.now` - URL: `https://api.sonovault.now/v1/releases/{id}` - Auth: API key in header `x-api-key` Get release by ID. Returns the release fields flat with nested artist and label objects, plus a peer tracks[] array where each track has ISRC, BPM, musical key, genre, subgenre, and artist credits. ## Path parameters - `id` integer, required ## Query parameters - `edition` integer ## Response `200` Successful response - object - `id` integer, required: Release ID. - `title` string, required: Release title. - `artist` ArtistRef, required: A minimal artist reference. Artists are always nested objects on the public API, never a flat `artist_name` column. - `id` integer, required: Artist ID. - `name` string, required: Artist name. - `label` LabelRef, required: A minimal label reference. - `id` integer, required: Label ID. - `name` string, required: Label name. - `release_date` string, nullable, required: Release date, `YYYY-MM-DD`. `null` when unknown. - `catalog_no` string, nullable, required: The label's catalog number. `null` when unknown. - `musicbrainz_release_ids` string[], required: MusicBrainz release MBIDs, sorted. An array rather than a single value because a SonoVault release groups every edition of an album and each edition carries its own MBID, so you can pick the edition you need. Empty when unmapped. - `musicbrainz_release_group_ids` string[], required: MusicBrainz release-group MBIDs: the identity of the album across all its editions, as opposed to any one pressing. Usually a single entry. Empty when unmapped. - `tracks` ReleaseTrack[], required: The release's tracks in playing order: disc number, then track number, with any track whose position is unknown last. Numbering comes from the edition named by `?edition=`, or from a consensus across the release's editions when you do not name one. - `id` integer, required: Sonovault track ID. - `title` string, required: Track title. - `duration` integer, nullable, required: Duration in seconds. `null` when unknown. - `bpm` number, nullable, required: Tempo in beats per minute, up to two decimals (e.g. `123`, `123.48`). Measured by the Lexicon DJ beat detector on the audio itself, and reported at full tempo: a drum & bass track reads `174`, not the half-time `87`. `null` when the track has not been analysed yet. - `key_alphanumeric` string, nullable, required: Musical key in alphanumeric notation: a number from 1 to 12 plus `A` for minor or `B` for major (e.g. `10B`). Keys one step apart on the wheel, or with the same number, mix harmonically. Our preferred key, measured by OpenKeyScan. `null` when the track has not been analysed yet. - `key_musical` string, nullable, required: The same key in standard musical notation (e.g. `D`, `Am`, `F#m`, `Ebm`, `Db`). A trailing `m` means minor. `null` when the track has not been analysed yet. - `key_open` string, nullable, required: The same key in Open Key notation, lowercase: a number from 1 to 12 plus `d` for major or `m` for minor (e.g. `3d`, `1m`). `null` when the track has not been analysed yet. - `keys` TrackKey[], required: Every key we hold for the track, one entry per source, each in all three notations. The single `key_*` fields carry the preferred entry. Empty array when the track has not been analysed yet. - `key_alphanumeric` string, required: Alphanumeric notation, e.g. `10B` (1-12, `A` minor, `B` major). - `key_musical` string, required: Standard musical notation, e.g. `D`, `F#m`. - `key_open` string, required: Open Key notation, lowercase, e.g. `3d` (major) or `1m` (minor). - `source` string, required: Who measured this key. Currently always `openkeyscan` (our own analysis with OpenKeyScan). More sources may be added, so treat unknown values as valid. - `isrc` string, nullable, required: One representative ISRC. `null` when none is known. - `artists` TrackArtist[], required: Artist credits, primary artists first. - `id` integer, required: Artist ID. Use it with `GET /v1/artists/:id`. - `name` string, required: Artist name as credited. - `is_primary` boolean, required: `true` for a main artist, `false` for a featured or supporting credit. - `is_remixer` boolean, required: `true` when the credit is for a remix of the track. - `genre` string[], required: Canonical genres. Empty array when unclassified. - `subgenre` string[], required: Canonical subgenres. Empty array when none apply. - `disc_number` integer, nullable, required: Which disc the track sits on, counting from 1. `null` when the position is unknown. - `track_number` integer, nullable, required: Position of the track on this release, counting from 1 within its disc. A position belongs to the pairing of track and release rather than to the track alone, so the same recording can be track 6 on an album and track 2 on a compilation. `null` when the position is unknown. - `editions` ReleaseEdition[], required: The real editions behind this release, at most 20, chosen so that each is a genuinely different edition rather than twenty pressings of the same one. Empty when none are known. - `id` integer, required: Edition ID. Pass it as `?edition=` on `GET /v1/releases/:id` to get this edition's track numbering. - `source` 'spotify' | 'discogs' | 'musicbrainz', required: The provider describing this edition. - `external_id` string, required: The edition's ID at that provider: a Spotify album ID, a MusicBrainz release MBID, or a Discogs release ID. - `group_external_id` string, nullable, required: The provider's identity for the album across all its editions: a MusicBrainz release-group MBID or a Discogs master ID. `null` for Spotify, which has no such concept, and when the provider does not give one. - `title` string, nullable, required: The edition's own title, which often carries what makes it distinct ("Rumours (Super Deluxe)"). `null` when the provider gives none. - `edition_kind` 'album' | 'single' | 'ep' | 'compilation' | 'live' | 'remix' | 'soundtrack' | 'other' | 'null', nullable, required: What kind of release this edition is, normalised across providers. `null` when the provider does not say. - `format` 'cd' | 'vinyl' | 'cassette' | 'digital' | 'dvd' | 'mixed' | 'other' | 'null', nullable, required: Physical or digital format, normalised across providers. `null` when unknown. - `official` boolean, nullable, required: `false` for a release the provider marks unofficial, such as a bootleg. `null` when the provider does not say. - `release_date` string, nullable, required: The edition's release date, `YYYY-MM-DD`. Read it with `date_precision`: a month-precision date is reported as the first of the month. `null` when unknown. - `date_precision` 'day' | 'month' | 'year' | 'null', nullable, required: How much of `release_date` is real. `null` when there is no date. - `barcode` string, nullable, required: Barcode or UPC, digits only with leading zeros stripped, so the same edition can be matched across providers. `null` when unknown. - `country` string, nullable, required: Where the edition was issued, as the provider names it. Not an ISO code. `null` when unknown. - `medium_count` integer, nullable, required: How many discs, records or tapes the edition spans. `null` when unknown. - `track_count` integer, nullable, required: The provider's own total for the edition, including tracks SonoVault does not hold. Compare with `tracks_on_row` to see the gap. `null` when the provider does not say. - `tracks_on_row` integer, required: How many of this release's tracks sit on the edition. - `label` LabelRef, required: A minimal label reference. - `id` integer, required: Label ID. - `name` string, required: Label name. - `catalog_no` string, nullable, required: The pressing's catalog number, as printed on the release. Comes from Discogs and MusicBrainz, so Spotify editions have none. `null` when unknown. - `edition` integer, nullable, required: The edition whose numbering `tracks` uses. `null` unless you passed `?edition=`. --- [API](https://skmtc.dev/sonovault/apis/sonovault-api.md) · [All operations](https://skmtc.dev/sonovault/apis/sonovault-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sonovault/apis/sonovault-api/revisions/0152fff23f2c?raw)