TypeScript SDK

A typed client for Node.js, so you call methods instead of building requests.

bash
npm install musiclink-api-sdk
ts
import { MusicLinkClient } from "musiclink-api-sdk";

const client = new MusicLinkClient({ apiKey: process.env.MUSICLINK_API_KEY });

const { data: [track] } = await client.resolveTrack("https://open.spotify.com/track/4cOdK2wGLETKBW3PvgPWqT");
track.platforms.apple_music;

It calls the v2 API: songs, albums and artists, with the same fields as Responses. Node 18 or newer; every method except health() needs a key.

Resolve

ts
const { data } = await client.resolve("https://open.spotify.com/album/6N9PS4QXF1D0OWPk0Sxtb4");
if (data[0].type === "album") data[0].upc;

const { data: [artist] } = await client.resolveArtist("https://open.spotify.com/artist/0gxyHStUsqpMadRV0Di1Qt");
const { data: [song] } = await client.resolveTrack("4cOdK2wGLETKBW3PvgPWqT", { platform: "spotify" });
resolve(q, options?)Track | Album | Artist

Anything resolve takes: a link, an ISRC, a UPC, a MusicLink ID or link, or a bare ID with platform. The type is detected from q; check item.type.

resolveTrack · resolveAlbum · resolveArtistTrack[] · Album[] · Artist[]

The same, with the type set. resolveTrack can return more than one song when versions share an ISRC.

optionsobject

type (resolve only), platform, include (an array: related.artists, related.album, platform_ids) and signal, an AbortSignal.

Each result has the API's fields, with missing values as null, plus two helpers: getLink("spotify") and getEmbedUrl({ layout, theme }) (layouts full, compact, list, rail, slim; themes dark, light, artwork; EMBED_HEIGHTS has each layout's iframe height).

Songs and albums already on MusicLink come from the cache, so a MusicLink ID or link is the quick way to look one up again:

ts
await client.resolveTrack("huUKtw-D");
await client.resolveTrack("https://musiclink.one/song/rick-astley/never-gonna-give-you-up");

Convert

ts
const { data } = await client.convert("https://open.spotify.com/track/4cOdK2wGLETKBW3PvgPWqT", "isrc");
data.to.value; // "GBARL9300135"
convert(q, to, options?)Conversion

One answer from convert: data.to.value, data.from and data.item. Options: type, platform, signal.

convertTrack · convertAlbum · convertArtistConversion

The same, with the type set, so to only accepts that type's values: isrc for songs, upc for albums.

Client options

apiKeystring

Your key from the dashboard.

timeoutMsnumber

Default: 30000. A first lookup takes 10–15 seconds.

userAgentstring

Your app's name and version, like MyApp/1.0 (https://myapp.com). Sent ahead of the SDK's own.

baseUrl · webUrl · fetch

For self-hosting, local development, or your own fetch.

Errors

A failed request throws MusicLinkError, with status and message; retryAfter on 429 and 503, plan when the monthly limit is reached. A timeout or network failure has status 0. What each status means.

Upgrading from 0.1

query(q) and lookup(platform, id) still work, through v2; prefer resolveTrack. The keyless resolve(id) and resolveBySlug are gone: pass the ID or the MusicLink link to resolveTrack. On results, links is now platforms and public_id is now id.

Ready to build?

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