API Reference

SongPort API

Turn one music link into links for Spotify, Apple Music, YouTube Music, Deezer, Tidal and SoundCloud, with the same ISRC matching that runs songport.link. One request in, all the platform links out.

Overview

The SongPort API resolves a music link (from Spotify, Apple Music, YouTube Music, Deezer or Tidal) into the matching links on the other platforms and a search link for SoundCloud, plus the track's title, artist and artwork. It's the programmatic version of what the website does when you paste a link.

It's a single JSON endpoint. You send a link, you get back a structured object with a link per platform.

By default the API runs on SongPort's managed platform keys. Your SongPort API key is enough: no Spotify, Apple Music, TIDAL or YouTube setup on your side. If you later want to bring your own credentials (higher volume, your own upstream quota), see Platform credentials.

Base URL

All requests go to:

https://api.songport.link/v1

Every endpoint below is relative to that base and uses HTTPS.

Authentication

Requests are authenticated with an API key, sent as a bearer token in the Authorization header:

Authorization: Bearer sp_live_xxxxxxxxxxxxxxxxxxxx

Your key is secret and meant for server-to-server use only. Keep it in your backend, never ship it in browser or mobile-app code, where it could be read and reused. There are no CORS headers on the API for exactly this reason. If a key is ever exposed, it can be revoked instantly and a new one issued.

Don't have a key yet? Email me (see Support) and I'll set you up. Access is invite-only for now.

A newly issued key is active immediately. You can call /v1/convert as soon as you accept the invite. An inactive or revoked key returns 401.

Platform credentials

Default: managed keys. Conversions run on SongPort's shared Spotify, Apple Music, TIDAL and YouTube credentials. You do not configure anything. That shared pool has a daily capacity ceiling (see Rate limits & quota), so invite-only stays in place until that capacity grows.

Optional: bring your own keys (BYOK). If you need volume beyond the shared pool, or want to draw on your own upstream quota, tell me and I'll enable the credentials section in your portal (/portal/credentials). Once every required provider is configured, your account skips the shared daily ceiling.

PlatformWhat you provide (BYOK)Notes
deezerNothingOpen public endpoint. Always available, no key needed.
youtubeMusicA YouTube Data API keyFree from Google Cloud. Matches by title/artist (YouTube has no ISRC).
spotifyClient ID + secretBest ISRC coverage.
appleMusicMusicKit key (Team ID, Key ID, .p8)ISRC lookup swept across regional storefronts. Needs a paid Apple Developer account.
tidalClient ID + secretMatches by ISRC only. No text search.
soundcloudNothingNo direct-match lookup. Always returned as a search link (isSearchFallback: true).

On a BYOK account, a platform you have not configured falls back to the managed key for that provider. Fully managed accounts never see this section in the portal.

Converting a link

POST /v1/convert resolves one music link.

Send a JSON body with these fields:

FieldTypeRequiredDescription
urlstringyesA supported music URL (or a spotify: URI).
platformsstring[]noOnly return these platforms (e.g. ["spotify", "appleMusic"]). Unknown keys are ignored. See below for what it changes about the lookup.
shortenbooleannoWhen true, the response of a new conversion carries a shareable songport.link URL (songportUrl).

Platform keys: spotify, appleMusic, youtubeMusic, deezer, tidal, soundcloud.

A new conversion is stored either way, so the next request for the same link is a cache hit. platforms changes the lookup too: without shorten, SongPort skips the platforms you did not name (never the platform of the link itself) and stores nothing, so there is no songportUrl and the next request resolves again. With shorten: true, every platform is looked up and stored, and platforms only narrows the response. A cache hit is filtered to your platforms.

As a source the API reads links from Spotify, Apple Music, YouTube Music, Deezer and Tidal. It does not read SoundCloud links: one returns 422 with code: "UNSUPPORTED_CONTENT", unless SongPort already has that exact link stored. The same goes for playlists, artist pages, podcasts and audiobooks: the API converts songs and albums.

Album and release links work too: when the source resolves to a release, the response carries a upc (the release-level analogue of isrc) alongside the per-platform links.

The response

A successful call returns 200 with a JSON object:

200 OK
{
  "isrc": "GBARL9300135",
  "upc": null,
  "title": "Never Gonna Give You Up",
  "artist": "Rick Astley",
  "thumbnail": "https://i.scdn.co/image/ab67616d...",
  "platforms": {
    "spotify":    { "url": "https://open.spotify.com/track/4cOd...", "isSearchFallback": false },
    "appleMusic": { "url": "https://music.apple.com/...",           "isSearchFallback": true  },
    "deezer":     { "url": "https://www.deezer.com/track/781592622", "isSearchFallback": false }
  },
  "cached": true,
  "songportUrl": "https://songport.link/t/rick-astley-never-gonna-give-you-up-w45sq8xg"
}

What each field means:

FieldTypeDescription
isrcstring | nullThe recording's ISRC, or null when SongPort holds none. Returned on cache hits too.
upcstring | nullThe release's UPC, the album-level analogue of isrc, or null. Every response carries the key, cache hits included.
titlestringTrack title.
artiststringArtist name.
thumbnailstring | nullCover-art image URL.
platformsobjectA map of platform key → { url, isSearchFallback }. See below.
cachedbooleantrue when the song was already known to SongPort, so the result comes from its store.
songportUrlstring?A shareable short link. Present on a cache hit, and on a new conversion when you pass shorten: true.

Each entry in platforms has a url and a boolean isSearchFallback:

  • isSearchFallback: false: a direct deep link to the exact track on that platform.
  • isSearchFallback: true: no direct link was produced, so the URL is a best-effort search on that platform instead. Common reasons: the track isn't on that catalogue, or (on a BYOK account) that platform's credential isn't configured yet.

Examples

A minimal request with cURL:

cURL
curl -X POST https://api.songport.link/v1/convert \
  -H "Authorization: Bearer sp_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://open.spotify.com/track/4cOdK2wGLETKBW3PvgPWqT"}'

The same call from a Node.js backend:

JavaScript (server-side)
const res = await fetch("https://api.songport.link/v1/convert", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SONGPORT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://open.spotify.com/track/4cOdK2wGLETKBW3PvgPWqT",
    platforms: ["spotify", "appleMusic"], // optional
  }),
})

const data = await res.json()
console.log(data.platforms.appleMusic.url)

Errors

Every error is JSON with a sentence in error and a stable code. Match on code: codes are added, never renamed, and the sentence may change. The sentence is SongPort's own and never passes on text from a music service.

502
{
  "error": "Spotify isn't responding right now. Try again in a little while.",
  "code": "UPSTREAM_UNAVAILABLE",
  "platform": "spotify"
}
StatuscodeMeaning
400INVALID_REQUESTThe body is not JSON, url is missing or blank, or platforms is not an array of strings.
400INVALID_URLurl is not a link to Spotify, Apple Music, YouTube Music, Deezer or Tidal.
401UNAUTHORIZEDMissing, invalid, or inactive API key.
403terms_not_acceptedAccept the current API terms in the portal. Lower case for historical reasons.
422UNSUPPORTED_CONTENTContent the API does not convert, with a reason: playlist, artist, soundcloud, podcast, audiobook, video or short.
422NOT_FOUNDThe source could not be read, or no match passed verification.
429QUOTA_EXCEEDEDlimit: "monthly": the monthly quota is spent (see below). limit: "daily": this key's daily cap on new conversions is spent, for a rolling 24 hours. A link SongPort has seen before keeps working.
429RATE_LIMITEDlimit: "minute": more than 120 requests in a minute; wait for Retry-After (60 seconds). limit: "capacity": the shared daily capacity of the managed keys is spent. A link SongPort has seen before keeps working.
502UPSTREAM_UNAVAILABLEThe music service in platform did not answer (null when unknown). Retry after Retry-After (30 seconds unless the service asked for longer).
502UPSTREAM_CREDENTIALS_REJECTEDBring-your-own-keys only: the service in platform refused the credentials you added for it. Check them in /portal/credentials; retrying does not help until then.
502INTERNAL_ERRORSomething failed on SongPort's side. Safe to retry.

Rate limits & quota

Each account has a monthly quota (calls per month, shared by every key on the account) and a short per-minute burst limit. The month starts on the day the account was created, or the day it last moved to a higher quota.

Every successful call counts as one call toward the monthly quota, cache hits included. A failed call (any status of 400 or higher) does not. Every call that gets past the key check, failed or not, counts toward the per-minute limit of 120 requests, so a client that keeps sending a broken link slows down like any other busy client. A call refused by the key check itself (a 401, a 403, or a 429 for the monthly quota or the per-minute limit) is not counted.

Once the quota is spent, every call returns 429 until it resets. Retrying does not help. The response links to the billing portal. Pick a higher plan there and pay in Stripe. The quota on your account updates when the payment lands.

Each key also has a daily cap on new conversions (a rolling 24 hours). Only successful new conversions count; cache hits and failed calls do not.

On managed keys (the default), there is also a shared daily capacity ceiling that protects the live site. A full ceiling returns 429 until the next day. Fully BYOK accounts (every provider configured) skip that shared ceiling and only hit their plan quota and burst limit.

Versioning

The API is versioned in the path (/v1). v1 is a stable contract: responses only gain fields. Existing ones are never removed or renamed. Any breaking change ships under a new major version (/v2), and v1 stays supported for a clearly-announced deprecation window after that.

Changelog

  • 2026-11-04. Every error is JSON with a stable code (see Errors). The 401 and 429 answers used to be plain text; the same sentence is now the error field. Statuses are unchanged. A 502 now says why in code, and error messages no longer pass on text from a music service.
  • 2026-11-04. Failed calls (status 400 and up) that get past the key check are now recorded. They count toward the per-minute limit, so a client that keeps sending a broken link now gets 429 RATE_LIMITED. They never count toward the monthly quota or the daily cap.
  • 2026-11-04. A playlist, artist page, podcast, audiobook or SoundCloud link now answers 422 with code: "UNSUPPORTED_CONTENT" and a reason. It used to answer 422 with code: "NOT_FOUND". A client that matched on NOT_FOUND for these links should match on UNSUPPORTED_CONTENT as well.
  • 2026-11-04. Cache hits return isrc and upc; every response carries both keys.
  • 2026-11-04. New conversions are stored even without shorten, so repeat requests are cache hits. Without shorten, platforms also limits the lookup, and that result is not stored.

Support

A higher plan is self-serve in the billing portal. Questions about the API: hello@songport.link.

Releasing music yourself? SongPort for Artists is a bio page with your releases. For artists.