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

bash
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.

RequestTry it
curl -G "https://api.musiclink.one/v2/resolve" \
  --data-urlencode "q=https://open.spotify.com/track/4cOdK2wGLETKBW3PvgPWqT" \
  -H "Authorization: Bearer $MUSICLINK_API_KEY"
Response · 200 OK
{
  "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, required

One 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 | artist

Optional. 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 below

Required 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):

Songs
  • musiclink
  • isrc
  • spotify
  • apple_music
  • youtube
  • youtube_music
  • soundcloud
  • deezer
  • tidal
Albums
  • musiclink
  • upc
  • spotify
  • apple_music
  • youtube_music
  • deezer
  • tidal
  • soundcloud
Artists
  • musiclink
  • spotify
  • apple_music
  • soundcloud
  • deezer
  • tidal
  • youtube_music
includecomma-separated list

Optional. 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.

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.

RequestTry it
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"
Response · 200 OK
{
  "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, required

What you want back. The values depend on what q is:

Songs
  • spotify
  • apple_music
  • youtube
  • youtube_music
  • deezer
  • tidal
  • soundcloud
  • amazon_music
  • amazon_store
  • pandora
  • qobuz
  • yandex
  • boomplay
  • anghami
  • audiomack
  • shazam
  • jiosaavn
  • bandcamp
  • isrc
Albums
  • spotify
  • apple_music
  • youtube_music
  • deezer
  • tidal
  • soundcloud
  • amazon_music
  • pandora
  • audiomack
  • anghami
  • boomplay
  • jiosaavn
  • bandcamp
  • qobuz
  • shazam
  • yandex
  • amazon_store
  • upc
Artists
  • spotify
  • apple_music
  • deezer
  • tidal
  • soundcloud
  • youtube_music
  • youtube
  • amazon_music
  • pandora
  • audiomack
  • anghami
  • jiosaavn
  • qobuz
  • bandcamp
q · type · platform

The same as in resolve.

The response's data is a single object:

data.to.valuestring

The answer: a URL for a platform, the 12-character ISRC for isrc, the 12–14 digit UPC for upc.

data.fromobject

Where q was read from: platform (a key from Platforms) and id (that service's ID).

data.itemobject or null

For 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

InputFormatExampleAlso send
LinkA 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:… URIhttps://open.spotify.com/track/4cOdK2wGLETKBW3PvgPWqT— (a link says what it is, so type and platform are ignored)
ISRC12 characters: 2 letters, 3 letters or digits, 7 digits. Dashes are fineGBARL9300135—
UPC12–14 digits; always an album0724384960650—
MusicLink IDThe id from an earlier responsehuUKtw-Dplatform=musiclink, and type for an album or artist
Service IDThe ID in that service's own link4cOdK2wGLETKBW3PvgPWqTplatform (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.

ts
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

ts
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

ts
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

ts
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

ts
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 };
}

With include=related.artists or include=related.album, songs and albums get a related object with just the parts you asked for.

ts
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.

StatusMeansDo
400A parameter is missing or invalid; error names it.Fix the request. Don't retry it as is.
401The key is missing, wrong or revoked.Send Authorization: Bearer <key> with an active key.
404Nothing matched q.Check the input. For a bare ID, send platform (and type for albums and artists).
422Convert can't handle this q.Send the same request to resolve.
429Over a rate limit.Wait the number of seconds in the Retry-After header, then retry.
500Something failed on our side.Retry after a few seconds.

Rate limits

Limits apply per account, shared by all of its keys.

PlanPer monthPer secondPer minute
Free300110
Hobby5,000260
Developer15,0003120
Pro50,0005200

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.

  • MusicLinkmusiclink
  • Spotifyspotify
  • ISRCisrc
  • UPCupc
  • Apple Musicapple_music
  • YouTubeyoutube
  • YouTube Musicyoutube_music
  • Deezerdeezer
  • TIDALtidal
  • SoundCloudsoundcloud
  • Amazon Musicamazon_music
  • Amazon Storeamazon_store
  • Pandorapandora
  • Qobuzqobuz
  • Yandex Musicyandex
  • Boomplayboomplay
  • Anghamianghami
  • Audiomackaudiomack
  • Shazamshazam
  • JioSaavnjiosaavn
  • Bandcampbandcamp

Ready to build?

Create a free key and send your first request in a minute.