Quick start

curl -X POST https://linkedapp.ddns.net/api/resolve \
  -H "Content-Type: application/json" \
  -d '{"url": "https://open.spotify.com/track/1wNgc05aCdwZHRuC9wMixm"}'

Endpoints

POST/api/resolveresolve

Resolve a music URL into a universal Linked URL with cross-platform links, lyrics, and previews.

ParameterTypeInDescription
url*stringbodyMusic URL from a supported platform
GET/api/entity/:type/:identity

Resolve a Linked ID back to full metadata with cross-platform links.

ParameterTypeInDescription
type*stringpathEntity type: song, album, artist, podcast, or audiobook
id*stringpathLinked ID (e.g. sp-1wNgc05aCdwZHRuC9wMixm)
GET/api/lyricslyrics

Fetch lyrics for a track via the keyless Lrclib API.

ParameterTypeInDescription
track*stringqueryTrack name
artist*stringqueryArtist name
albumstringqueryAlbum name (improves match)
durationnumberqueryTrack duration in seconds (improves match)
GET/api/ogog

Generate a dynamic 1200x630 Open Graph share image (SVG) for social cards.

ParameterTypeInDescription
title*stringqueryEntity title
artiststringqueryArtist name
imagestringqueryCover art URL
themestringquery'dark' or 'light'
GET/api/oembedoembed

oEmbed endpoint for rich previews (Twitter, Discord, Slack).

ParameterTypeInDescription
url*stringqueryMusic URL from a supported platform
maxwidthnumberqueryMax embed width (200-1200, default 600)
themestringquery'light' or 'dark'
GET/api/searchsearch

Search for tracks, albums, or artists across platforms (Deezer, Spotify, Apple).

ParameterTypeInDescription
q*stringquerySearch query
typestringquerytrack / album / artist
limitnumberqueryResults (1-25, default 10)
sourcesstringqueryComma-separated: deezer, spotify, apple
GET/api/healthhealth

Health check for the API and downstream services.

GET/api/docsdocs

This page. Full API reference.

Platforms

Input platforms

Source URLs accepted by /api/resolve.

Spotify (sp)
Apple Music (am)
Deezer (dz)
Tidal (td)
YouTube (yt)
Amazon Music (az)
Bandcamp (bc)

Output platforms

Cross-link services generated by resolution.

Spotify
Apple Music
Deezer
Tidal
YouTube
YouTube Music (ytm)
Amazon Music (azm)
Bandcamp

Linked IDs

Every entity gets a compact, URL-safe Linked ID. Format: {type}{platform}-{id}

sp-1wNgc05aCdwZHRuC9wMixm
song · Spotify
al-3qTXcsxYQGjBOZ8Ds2ZkyG
album · Spotify
at-0MZ55DwuMQ1B2TXq9lcrE4
artist · Spotify
Codes
Type: s = song   l = album   a = artist
Platform: sp = Spotify   dz = Deezer   td = Tidal   am = Apple Music   yt = YouTube   az = Amazon Music   ytm = YouTube Music   azm = Amazon Music   bc = Bandcamp

Entity types

🎵song

A single track. ISRC is used to cross-resolve links across platforms. Includes lyrics + previews.

Resolves to: Spotify, Deezer, Apple Music, Tidal, YouTube, YouTube Music, Amazon Music
💿album

An album or EP. Cross-links are resolved by searching album name + artist.

Resolves to: Spotify, Deezer, Apple Music, Tidal*, YouTube, YouTube Music, Amazon Music*
* Requires elevated API access (Tidal: THIRD_PARTY tier; Amazon Music: API key).
🎤artist

An artist profile. Cross-links are resolved by searching the artist name.

Resolves to: Spotify, Deezer, Apple Music, Tidal*, YouTube (channel), YouTube Music, Amazon Music*
* Requires elevated API access (Tidal: THIRD_PARTY tier; Amazon Music: API key).
🎙️podcast / audiobook

Recognized but not cross-linkable. Shows a graceful region-aware fallback.

Resolves to: Not yet supported

Rate limit & CORS

⚡

Rate limit

Resolve and search endpoints are limited to 30 requests/minute per IP. Responses include X-RateLimit-Remaining / X-RateLimit-Reset headers.

🌐

CORS

All endpoints return Access-Control-Allow-Origin: *. You can call the API from any origin, including browser-side code.

Service health

Check the live health of all downstream services at /api/health. Key services (Deezer, Apple Music, YouTube) are marked required — if any go down the API reports degraded.

Deezerrequired
Keyless ISRC + metadata lookup
Apple Musicrequired
Keyless iTunes lookup + search
YouTuberequired
Keyless oEmbed + search
Spotify
Client credentials (SPOTIFY_CLIENT_ID/SECRET)
Tidal
Client credentials (TIDAL_CLIENT_ID/SECRET); artist/album search needs THIRD_PARTY tier