API Reference

Examples

Working examples for every endpoint. Copy and run them in your terminal or application.

POST/api/resolveresolve

Resolve a music URL

Take any supported music URL and get back a Linked URL with links to every platform.

Request parameters

Parameters:
url="https://open.spotify.com/track/1wNgc05aCdwZHRuC9wMixm"

Code examples

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

Example response

{
  "linkedUrl": "/song/ssp-1wNgc05aCdwZHRuC9wMixm",
  "linkedId": "ssp-1wNgc05aCdwZHRuC9wMixm",
  "entity": {
    "name": "The Less I Know The Better",
    "artist": "Tame Impala",
    "image": "https://i.scdn.co/image/ab67616d0000b273...",
    "year": 2015,
    "links": {
      "spotify": "https://open.spotify.com/track/1wNgc05aCdwZHRuC9wMixm",
      "apple": "https://music.apple.com/...",
      "deezer": "https://www.deezer.com/track/...",
      "tidal": "https://tidal.com/browse/track/...",
      "youtube": "https://www.youtube.com/watch?v=p3oxS5k4Suo",
      "youtubemusic": "https://music.youtube.com/watch?v=p3oxS5k4Suo"
    }
  },
  "source": {
    "platform": "spotify",
    "type": "song",
    "platformId": "1wNgc05aCdwZHRuC9wMixm",
    "url": "https://open.spotify.com/track/1wNgc05aCdwZHRuC9wMixm"
  }
}

GET/api/entity/{type}/{id}entity

Resolve a Linked ID

Look up a Linked ID to get all cross-platform links and full metadata.

Request parameters

Parameters:
type="song"
id="sp-1wNgc05aCdwZHRuC9wMixm"

Code examples

curl https://linkedapp.ddns.net/api/entity/song/sp-1wNgc05aCdwZHRuC9wMixm

Example response

{
  "type": "song",
  "id": "sp-1wNgc05aCdwZHRuC9wMixm",
  "title": "The Less I Know The Better",
  "artist": "Tame Impala",
  "album": "Currents",
  "year": 2015,
  "duration": 214,
  "isrc": "USQX91500601",
  "links": {
    "spotify": "https://open.spotify.com/track/1wNgc05aCdwZHRuC9wMixm",
    "appleMusic": "https://music.apple.com/track/1440885405",
    "deezer": "https://www.deezer.com/track/1023921722",
    "tidal": "https://tidal.com/browse/track/122998414",
    "youtube": "https://www.youtube.com/watch?v=p3oxS5k4Suo",
    "youtubeMusic": "https://music.youtube.com/watch?v=p3oxS5k4Suo",
    "amazonMusic": "https://music.amazon.com/tracks/B00S66QOI6"
  }
}

GET/api/oembedoembed

Get an oEmbed preview

Generate a rich oEmbed card for Twitter, Discord, Slack, and other oEmbed consumers.

Request parameters

Parameters:
url="https://open.spotify.com/track/1wNgc05aCdwZHRuC9wMixm"
maxwidth=600

Code examples

curl "https://linkedapp.ddns.net/api/oembed?url=https%3A//open.spotify.com/track/1wNgc05aCdwZHRuC9wMixm&maxwidth=600"

Example response

{
  "type": "rich",
  "version": "1.0",
  "title": "The Less I Know The Better — Tame Impala",
  "author_name": "Linked",
  "provider_name": "Linked",
  "provider_url": "https://linkedapp.ddns.net",
  "html": "<iframe ...></iframe>",
  "width": 600,
  "height": 200
}

GET/api/searchsearch

Search for music

Search across platforms by query. Returns tracks, albums, or artists.

Request parameters

Parameters:
q="blinding lights"
type="track"
limit=5

Code examples

curl "https://linkedapp.ddns.net/api/search?q=blinding%20lights&type=track&limit=5"

Example response

{
  "type": "track",
  "total": 1,
  "data": [
    {
      "id": 6624,
      "title": "Blinding Lights",
      "duration": 200,
      "artist": { "id": 359侶, "name": "The Weeknd" },
      "album": { "id": 8573伕, "title": "After Hours" }
    }
  ]
}

GET/api/lyricslyrics

Fetch lyrics

Get lyrics for any track via the keyless Lrclib API. Returns plain and synced lyrics.

Request parameters

Parameters:
track="The Less I Know The Better"
artist="Tame Impala"
album="Currents"

Code examples

curl "https://linkedapp.ddns.net/api/lyrics?track=The%20Less%20I%20Know%20The%20Better&artist=Tame%20Impala&album=Currents"

Example response

{
  "plainLyrics": "She was holding hands with Trevor\nNot the greatest feeling ever\nSaid, pull yourself together\nTry another drink...",
  "syncedLyrics": "[00:16.92] She was holding hands with Trevor\n[00:20.04] Not the greatest feeling ever...",
  "instrumental": false,
  "source": "lrclib"
}

GET/api/ogog

Generate an OG share image

Create a styled 1200x630 Open Graph image for social sharing (Twitter cards, Discord embeds, WhatsApp).

Request parameters

Parameters:
title="The Less I Know The Better"
artist="Tame Impala"
theme="dark"

Code examples

curl -o card.svg "https://linkedapp.ddns.net/api/og?title=The%20Less%20I%20Know%20The%20Better&artist=Tame%20Impala&theme=dark"

Example response

<!-- SVG response with Content-Type: image/svg+xml -->
<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630">
  <defs>
    <linearGradient id="bg" ...
    <linearGradient id="accent" ...
  </defs>
  <rect width="1200" height="630" fill="url(#bg)"/>
  <image x="80" y="140" width="300" height="300" rx="24" .../>
  <text x="440" y="220" font-size="48" font-weight="700">The Less I Know...</text>
  <rect x="440" y="340" width="200" height="50" rx="25" fill="url(#accent)"/>
  <text x="540" y="372" font-size="20">Open in Linked</text>
</svg>

GET/api/healthhealth

Check service health

Get the live health status of the API and all downstream music services.

Code examples

curl https://linkedapp.ddns.net/api/health

Example response

{
  "status": "operational",
  "timestamp": "2025-01-15T12:00:00Z",
  "services": {
    "deezer": { "status": "up", "latency_ms": 42 },
    "appleMusic": { "status": "up", "latency_ms": 78 },
    "youtube": { "status": "up", "latency_ms": 55 },
    "spotify": { "status": "up", "latency_ms": 31 },
    "tidal": { "status": "up", "latency_ms": 120 }
  }
}