API Reference
Send one link, ISRC or UPC. Get back the same song, album or artist on every streaming platform.
Authentication
All requests require an Authorization: Bearer <key> header. Get yours from the dashboard. Base URL: https://api.musiclink.one
curl "https://api.musiclink.one/v2/resolve?q=GBARL9300135" \
-H "Authorization: Bearer <your-key>"Send a request
GET/v2/resolve?q=<input>
Resolve takes one thing you know about a song, album or artist and returns its link on every platform, with its details.
curl -G "https://api.musiclink.one/v2/resolve" \
--data-urlencode "q=https://open.spotify.com/track/4cOdK2wGLETKBW3PvgPWqT" \
-H "Authorization: Bearer $MUSICLINK_API_KEY"{
"success": true,
"data": [
{
"type": "track",
"id": "h8aN_1K9",
"url": "https://musiclink.one/song/rick-astley/never-gonna-give-you-up?i=2",
"embed_url": "https://musiclink.one/embed/s/h8aN_1K9",
"title": "Never Gonna Give You Up",
"artist": "Rick Astley",
"image_url": "https://is1-ssl.mzstatic.com/image/thumb/Music124/v4/ce/6d/5b/ce6d5b48-8c36-b990-3b9c-81862fadb459/0859381157694.jpg/600x600bb.jpg",
"isrc": "GBARL0600786",
"duration_ms": 213573,
"preview_url": "https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview221/v4/62/ff/3a/62ff3abe-bc6d-a7d0-31b0-71cbec9aaa24/mzaf_13802296211720217737.plus.aac.p.m4a",
"platforms": {
"musiclink": "https://musiclink.one/song/rick-astley/never-gonna-give-you-up?i=2",
"spotify": "https://open.spotify.com/track/4cOdK2wGLETKBW3PvgPWqT",
"apple_music": "https://music.apple.com/song/1559885421",
"deezer": "https://www.deezer.com/track/14408104",
"tidal": "https://listen.tidal.com/track/491206012",
"youtube": "https://youtube.com/watch?v=dQw4w9WgXcQ",
"soundcloud": "https://soundcloud.com/pajlada/rick-astley-never-gonna-give-you-up",
"qobuz": "https://open.qobuz.com/track/385574059",
"audius": "https://audius.co/tracks/4k3v4",
"shazam": "https://www.shazam.com/song/1773293184/never-gonna-give-you-up",
"yandex": "https://music.yandex.ru/track/609676",
"anghami": "https://play.anghami.com/song/106295734?refer=linktree",
"napster": "https://play.napster.com/track/tra.416878691",
"pandora": "https://www.pandora.com/TR:8526",
"bandcamp": "https://matthewrobertadamski2.bandcamp.com/track/never-gonna-give-you-up-2",
"boomplay": "https://www.boomplay.com/songs/3569876",
"jiosaavn": "https://www.jiosaavn.com/song/never-gonna-give-you-up/HzkgaC4dDgI",
"audiomack": "https://audiomack.com/rick-astley/song/never-gonna-give-you-up-1",
"amazon_music": "https://music.amazon.com/albums/B0DZTQLXGX?trackAsin=B0DZTSF3YS",
"amazon_store": "https://amazon.com/dp/B0DZTSF3YS",
"youtube_music": "https://music.youtube.com/watch?v=dQw4w9WgXcQ"
}
}
]
}The first lookup of an item searches every platform and takes 10–15 seconds, so set a 30-second timeout. Later lookups of the same item come from cache.
qstring, requiredOne of the inputs: a link, an ISRC, a UPC, a MusicLink ID, or a service's own ID. Up to 2,048 characters, URL-encoded.
typetrack | album | artistOptional. Default: detected from q; a bare ID counts as a track. Set album or artist when q is the ID of an album or an artist. song is accepted as track.
platformone of the values belowRequired when q is a bare ID, otherwise leave it out. Which values work depends on what the ID is for (apple works too, for apple_music):
musiclinkisrcspotifyapple_musicyoutubeyoutube_musicsoundclouddeezertidal
musiclinkupcspotifyapple_musicyoutube_musicdeezertidalsoundcloud
musiclinkspotifyapple_musicsoundclouddeezertidalyoutube_music
includecomma-separated listOptional. Default: nothing extra. Any of: related.artists (every credited artist; songs and albums), related.album (the album a song is on; songs only), platform_ids (each service's own ID). See Responses.
Convert one link
GET/v2/convert?q=<input>&to=<target>
Convert answers one question, like "what's this song's ISRC?" or "what's its Apple Music link?", and searches only that one platform, so it's faster.
curl -G "https://api.musiclink.one/v2/convert" \
--data-urlencode "q=https://open.spotify.com/track/4cOdK2wGLETKBW3PvgPWqT" \
--data-urlencode "to=isrc" \
-H "Authorization: Bearer $MUSICLINK_API_KEY"{
"success": true,
"data": {
"type": "track",
"input": {
"q": "https://open.spotify.com/track/4cOdK2wGLETKBW3PvgPWqT",
"to": "isrc"
},
"from": {
"platform": "spotify",
"id": "4cOdK2wGLETKBW3PvgPWqT"
},
"to": {
"platform": "isrc",
"value": "GBARL0600786"
},
"item": {
"title": "Never Gonna Give You Up",
"artist": "Rick Astley",
"image_url": "https://is1-ssl.mzstatic.com/image/thumb/Music124/v4/ce/6d/5b/ce6d5b48-8c36-b990-3b9c-81862fadb459/0859381157694.jpg/600x600bb.jpg",
"isrc": "GBARL0600786",
"duration_ms": 213573
}
}
}toone of the values below, requiredWhat you want back. The values depend on what q is:
spotifyapple_musicyoutubeyoutube_musicdeezertidalsoundcloudamazon_musicamazon_storepandoraqobuzyandexboomplayanghamiaudiomackshazamjiosaavnbandcampisrc
spotifyapple_musicyoutube_musicdeezertidalsoundcloudamazon_musicpandoraaudiomackanghamiboomplayjiosaavnbandcampqobuzshazamyandexamazon_storeupc
spotifyapple_musicdeezertidalsoundcloudyoutube_musicyoutubeamazon_musicpandoraaudiomackanghamijiosaavnqobuzbandcamp
q · type · platformThe same as in resolve.
The response's data is a single object:
data.to.valuestringThe answer: a URL for a platform, the 12-character ISRC for isrc, the 12–14 digit UPC for upc.
data.fromobjectWhere q was read from: platform (a key from Platforms) and id (that service's ID).
data.itemobject or nullFor display: title, artist and image_url, plus isrc and duration_ms for a song. For an artist, title is the name and artist is null. Can be null, for example when q itself already held the answer; don't depend on it.
404: the item isn't on the platform in to. 422: convert can't handle this q; send the same request to resolve.
Inputs
| Input | Format | Example | Also send |
|---|---|---|---|
| Link | A song, album or artist URL from a service in Platforms, a share link that redirects to one (link.deezer.com, spotify.link, on.soundcloud.com, apple.co), or a spotify:track:… URI | https://open.spotify.com/track/4cOdK2wGLETKBW3PvgPWqT | — (a link says what it is, so type and platform are ignored) |
| ISRC | 12 characters: 2 letters, 3 letters or digits, 7 digits. Dashes are fine | GBARL9300135 | — |
| UPC | 12–14 digits; always an album | 0724384960650 | — |
| MusicLink ID | The id from an earlier response | huUKtw-D | platform=musiclink, and type for an album or artist |
| Service ID | The ID in that service's own link | 4cOdK2wGLETKBW3PvgPWqT | platform (like spotify), and type for an album or artist |
One recording can be on several releases (a single, an album, a compilation), so an ISRC can return several items in data. Each item's platforms links to the same song; data[0] is enough for a link.
Responses
Resolve answers with one of two shapes: a list of matches, or an error with an error status.
type ResolveResponse =
| { success: true; data: Item[] } // one item per match
| { success: false; error: string };
type Item = Song | Album | Artist;A field with no value is left out, never null, so the fields marked ? may be missing. New fields may be added; ignore the ones you don't use.
Every item
interface BaseItem {
type: "track" | "album" | "artist";
id?: string; // MusicLink ID. Send it back as `q` with `platform=musiclink` for the fastest lookup
url?: string; // the item's MusicLink page
embed_url?: string; // a player for an <iframe>
image_url?: string; // artwork, or the artist's photo
platforms: { [key: string]: string }; // platform key → URL, only where it was found
platform_ids?: { [key: string]: string }; // platform key → that service's ID; only with include=platform_ids
}Platform keys are listed in Platforms; a missing key means the item wasn't found there.
Songs
interface Song extends BaseItem {
type: "track";
title?: string;
artist?: string; // artist credit, as on the release
isrc?: string; // 12-character recording code
duration_ms?: number; // length in milliseconds
preview_url?: string; // a 30-second audio clip
related?: Related; // with include=related.artists or related.album
}Albums
interface Album extends BaseItem {
type: "album";
title?: string;
artist?: string; // album artist
upc?: string; // 12–14 digit barcode
track_count?: number;
release_date?: string; // YYYY-MM-DD
related?: Related; // with include=related.artists
}Artists
interface Artist extends BaseItem {
type: "artist";
name?: string;
genres?: string[]; // like ["Pop"]
bio?: string; // short biography
// Only the networks found: website, instagram, twitter, facebook, tiktok, youtube, soundcloud, wikidata
social_links?: { [network: string]: string };
// Only what's known: born, formed, hometown, country, genre, musicbrainz_id, isni
artist_info?: { [key: string]: string };
}Related artists and album
With include=related.artists or include=related.album, songs and albums get a related object with just the parts you asked for.
interface Related {
artists?: RelatedEntry[];
album?: RelatedEntry;
}
interface RelatedEntry {
name: string; // artist or album name
id: string | null; // its MusicLink ID
status: "resolved" | "stub"; // stub: only its name and a few IDs are known yet
// resolved: its MusicLink page. stub: an API URL; request it with your key to get the full item
url: string | null;
query: string; // the same lookup as a path after /v2, like /resolve?q=mjfLhv4135mo&type=artist&platform=musiclink
image_url: string | null; // artwork or photo
}Errors
Every error body is { "success": false, "error": "<message>" }. Failed requests don't count toward your allowance.
| Status | Means | Do |
|---|---|---|
400 | A parameter is missing or invalid; error names it. | Fix the request. Don't retry it as is. |
401 | The key is missing, wrong or revoked. | Send Authorization: Bearer <key> with an active key. |
404 | Nothing matched q. | Check the input. For a bare ID, send platform (and type for albums and artists). |
422 | Convert can't handle this q. | Send the same request to resolve. |
429 | Over a rate limit. | Wait the number of seconds in the Retry-After header, then retry. |
500 | Something failed on our side. | Retry after a few seconds. |
Rate limits
Limits apply per account, shared by all of its keys.
| Plan | Per month | Per second | Per minute |
|---|---|---|---|
| Free | 300 | 1 | 10 |
| Hobby | 5,000 | 2 | 60 |
| Developer | 15,000 | 3 | 120 |
| Pro | 50,000 | 5 | 200 |
Over the per-second limit: 429, with Retry-After: 1 and "retryAfter": 1 in the body. Over the per-minute limit: the same with 60. Over the monthly allowance: 429 with no Retry-After and your plan in the body; requests work again on the 1st of the next month. Need more?
Platforms
These are the keys in platforms. Links depend on each service's catalog and region, so not every item has every key. isrc and upc are codes, not keys in platforms: convert returns them with to=isrc or to=upc.
- MusicLink
musiclink - Spotify
spotify - ISRC
isrc - UPC
upc - Apple Music
apple_music - YouTube
youtube - YouTube Music
youtube_music - Deezer
deezer - TIDAL
tidal - SoundCloud
soundcloud - Amazon Music
amazon_music - Amazon Store
amazon_store - Pandora
pandora - Qobuz
qobuz - Yandex Music
yandex - Boomplay
boomplay - Anghami
anghami - Audiomack
audiomack - Shazam
shazam - JioSaavn
jiosaavn - Bandcamp
bandcamp
Ready to build?
Create a free key and send your first request in a minute.