How an API request works

An endpoint is a URL that returns data for your app. You send a GET request with values in the URL, and usually receive JSON: named fields your code can read. No Spotify login or API key is required for the public lookups documented here.

Choose a route below. If you only want to try it, open its chapter and select Test API; you do not need to write any code.

Not sure where to start?

1. You have a Spotify track link

   Use Canvas media to check for a clip, or Resolve a track to obtain a reusable track ID first.

2. You only know the song name

   Use Search tracks with the artist and title. Check the returned match before using its ID.

3. You want an artist, not a song

   Use Artist profiles with an artist link, artist ID, or name. Track IDs and artist IDs are different.

Try it without writing code

1. Open the request tester

   Go to Resolve a track and select Test API, then Use example. The tester fills an example input and shows the request URL.

2. Send the request

   Select Send request. Read the HTTP status and JSON response on the right, or below the form on smaller screens. You can copy the request URL and response.

3. Read the result

   A successful lookup contains success: true and a trackId. Reuse that ID with Track metadata or Canvas media. If it fails, check the error code.

Understand the request URL

Append this path to this website’s address, or paste the full address copied from the tester into your browser. The word GET describes the HTTP method; do not type it into the address bar.

/api/resolve?id=0VjIjW4GlUZAMYd2vXMi3b

Use it from JavaScript

Run this inside an async function on this site, or in a browser console that supports top-level await. For a separate app or server, replace window.location.origin with this service’s full address. URLSearchParams encodes spaces and special characters for you.

const baseUrl = window.location.origin;
const params = new URLSearchParams({
  track: "The Weeknd - Blinding Lights"
});
const response = await fetch(
  baseUrl + "/api/resolve?" + params
);
const data = await response.json();

if (!response.ok || !data.success) {
  throw new Error(data.error || "Request failed");
}

console.log(data.trackId);
console.log(data.track?.name ?? "Metadata unavailable");

How to use it

1. Choose one input

   Send id for a known track, url for a full Spotify track link or URI, or track for an artist and song title.

2. Check the match

   Read trackId and, when available, track.name and track.artistNames. Text searches can find a different release or version.

3. Continue with the same ID

   Pass the returned trackId as id to Canvas media or Track metadata.

Example: resolve a song name

Copy this path after the site’s address. Spaces in the query are encoded as %20.

/api/resolve?track=The%20Weeknd%20-%20Blinding%20Lights&results=1

Check, then play

1. Request the JSON lookup

   Send /api/canvas?id=… without stream. A known ID avoids repeating a text search.

2. Check availability

   Read success, then hasCanvas. Only access canvases[0] when the array contains an item.

3. Use the returned video URL

   When available, open canvases[0].canvasUrl in the browser or use it as a video element’s source. That URL returns video bytes, so do not call response.json() on it.

Example: check availability

This returns JSON. Availability depends on the track and may change.

/api/canvas?id=0VjIjW4GlUZAMYd2vXMi3b

Example: handle the result

Run inside an async function. The code checks the array before reading the video URL.

const params = new URLSearchParams({
  id: "0VjIjW4GlUZAMYd2vXMi3b"
});
const response = await fetch("/api/canvas?" + params);
const data = await response.json();

if (!response.ok || !data.success) {
  throw new Error(data.error || "Canvas lookup failed");
}

const videoUrl = data.hasCanvas
  ? data.canvases?.[0]?.canvasUrl
  : null;

console.log(videoUrl ?? "No Canvas available");

How to use it

1. Include the artist and title

   Send a track query such as The Weeknd - Blinding Lights. Extra context helps distinguish songs with the same title.

2. Confirm the returned song

   Compare matchedTrack and matchedArtist with what you expected. Search matching does not guarantee your intended release.

3. Reuse the selected ID

   Send the top-level trackId to Track metadata or Canvas media. For an alternative candidate, use that item’s trackId.

Example request

The artist and title are encoded together as the track parameter.

/api/search?track=The%20Weeknd%20-%20Blinding%20Lights

How to use it

1. Get the track ID

   Copy the 22 characters after /track/ in a full Spotify track link, or use the trackId returned by resolve or search.

2. Send the ID as id

   Request /api/track?id=…. A full track URL or spotify:track:… URI can also be passed in id. A plain song title cannot.

3. Read the track object

   The metadata is inside track, rather than at the top level. Check optional fields before displaying them.

Example request

Use this path with the site’s address or open the tester above.

/api/track?id=0VjIjW4GlUZAMYd2vXMi3b

How to use it

1. Choose an artist input

   Send id or url for a specific artist. If you only know the name, send query; the first matched artist is selected.

2. Keep the response manageable

   Optionally set limit, such as 5, for supported related-item lists. This is not a limit on every collection in the response.

3. Start with summary

   Read summary.name, summary.avatarUrl, and summary.stats. Use the deeper objects for releases or extra profile data when available.

Example: search by artist name

This selects the first artist match. Confirm the returned artistName and reuse artistId for later requests.

/api/artist?query=The%20Weeknd&limit=5

Example: use an exact artist

Use an artist ID to avoid matching by name.

/api/artist?id=1Xyo4u8uXC1ZmMpatF05PJ&limit=5

Successful JSON lookups

HTTP 200 with success: true means the lookup completed. The remaining fields depend on the endpoint: a track ID, metadata, artist data, or Canvas availability. Fields such as source and request are endpoint-specific.

Example: a valid lookup without Canvas

This is an illustrative subset of a JSON response, not a live availability result. Other fields are omitted for clarity.

{
  "success": true,
  "trackId": "0VjIjW4GlUZAMYd2vXMi3b",
  "hasCanvas": false,
  "canvases": []
}

Failed JSON lookups

A handled failure returns a non-2xx HTTP status and a JSON object with success: false, a readable error, and a machine-readable code. Use the code for application decisions and show a helpful message to the user.

Example: a missing input

For example, calling /api/resolve without any input returns HTTP 400 with this error shape.

{
  "success": false,
  "error": "provide id, url, or track",
  "code": "missing_params"
}

What to send

Send only the public lookup inputs documented in each chapter: track or artist IDs, links, and search text. Do not include account passwords, Spotify access tokens, or private API keys in query strings. URLs can appear in browser history and network logs.

Build query strings with URLSearchParams so user input is encoded correctly. When displaying returned names or descriptions, use text content rather than inserting them as HTML.

When requests are limited

1. Recognize the response

   HTTP 429 with rate_limited or spotify_rate_limited means requests must pause. Different routes and service conditions can have different limits.

2. Wait before trying again

   When a Retry-After header is present, its value is the number of seconds to wait. Otherwise use a delayed retry with increasing waits and a small retry limit.

3. Avoid repeating the same work

   Reuse resolved IDs, keep recent results in your app, and prevent duplicate submissions while a lookup is running. Search after a deliberate user action instead of every keystroke.