TypeScript SDK

Typesafe Node.js and TypeScript client for the MusicLink API. Wraps every endpoint with full type inference — no manual fetch calls needed.

Install from npm Try it for free

Installation

npm install musiclink-api-sdk

Setup

Create a client with your API key. Get yours from the dashboard.

import { MusicLinkClient } from "musiclink-api-sdk";

const client = new MusicLinkClient({ apiKey: "your-api-key" });

Lookup

Resolve a track by platform ID or ISRC. Requires an API key.

client.lookup(platform, id)

const { data } = await client.lookup("spotify", "4cOdK2wGLETKBW3PvgPWqT");
const track = data[0];

console.log(track.title);      // "Never Gonna Give You Up"
console.log(track.artist);     // "Rick Astley"
console.log(track.isrc);       // "GBARL9300135"
console.log(track.image_url);  // "https://cdn..."
console.log(track.links);      // { spotify: "...", youtube: "...", apple_music: "...", ... }

platform	id format
"spotify"	Track ID — e.g. 4uLU6hMCjMI75M1A2tKUQC
"apple"	Full Apple Music URL
"deezer"	Track ID — e.g. 3135556
"tidal"	Track ID — e.g. 77325831
"isrc"	Bare ISRC — e.g. GBAHS1600463
"musiclink"	MusicLink public_id

ISRC example

const { data } = await client.lookup("isrc", "GBARL9300135");

First lookup: If a track has never been resolved, the API may take 10–15 seconds while it fetches data across platforms. Subsequent requests return from cache immediately.

Resolve

Look up a track by its MusicLink public ID or slug. No API key required.

// By public ID
const { data } = await client.resolve("huUKtw-D");

// By slug
const { data } = await client.resolveBySlug("rick-astley", "never-gonna-give-you-up");

These methods only work for tracks that already exist in MusicLink. If the track has never been looked up before, you will get a 404. Use lookup() instead to resolve a track from scratch.

Embed URL

Every track has a getEmbedUrl() helper that returns an iframe-ready URL.

// Default (full card, dark)
track.getEmbedUrl();
// → "https://ml.jadquir.com/embed/ml/huUKtw-D"

// Compact layout
track.getEmbedUrl({ compact: true });
// → "https://ml.jadquir.com/embed/ml/huUKtw-D?mode=compact"

// Compact + light theme
track.getEmbedUrl({ compact: true, light: true });
// → "https://ml.jadquir.com/embed/ml/huUKtw-D?mode=compact&theme=light"

Option	Default	Description
compact	false	Small horizontal layout with an icon grid
light	false	Light colour scheme (default is dark)

Drop into an iframe

<iframe
  src={track.getEmbedUrl({ compact: true })}
  width="400"
  height="160"
  frameborder="0"
/>

Error handling

All methods throw a MusicLinkError on non-2xx responses.

import { MusicLinkClient, MusicLinkError } from "musiclink-api-sdk";

try {
  const { data } = await client.lookup("spotify", "4cOdK2wGLETKBW3PvgPWqT");
} catch (err) {
  if (err instanceof MusicLinkError) {
    console.log(err.message);     // "Track not found."
    console.log(err.status);      // 404
    console.log(err.retryAfter);  // seconds to wait — set on 429 responses
  }
}

Property	Type	Description
message	string	Human-readable error from the API
status	number	HTTP status code
retryAfter	number \| undefined	Seconds to wait — present on 429 responses

Ready to build?

Go to dashboard npm API docs Try the playground