REST API

Tracklists as JSON.

Read every public set, artist and track on ryser.id. No key, plain HTTPS, JSON in and out, any origin, no SDK needed.

Access

There is no key and no account to create: every read endpoint is open to anyone. Requests are limited per address instead (see limits). Code that still sends an Authorization header from the days of read keys keeps working; the header is ignored.

http
GET /api/public/search?q=cercle HTTP/1.1
Host: ryser.id

Conventions

  • Base URL https://ryser.id. All read endpoints live under /api/public/.
  • Responses are JSON with snake_case fields. Times are ISO 8601 in UTC; durations and positions are seconds; start is also given as m:ss or h:mm:ss for display.
  • Every object carries its public url on ryser.id. Show it when you show the data.
  • CORS is open (Access-Control-Allow-Origin: *), so a browser can call the API directly.
  • Responses are cached for five minutes at the edge (Cache-Control: public, max-age=300). Polling faster than that returns the same body.
  • Rate limit: 60 requests per minute per address. Over it you get 429; wait for the next minute.
  • Only public, finished analyses are visible. A set someone kept private is a 404 here, exactly as on the site.
GET/api/public/sets/{id}no key

One public set with its full tracklist. The id is the uuid from search or from a ryser.id URL (https://ryser.id/s/<id>). Rows come in playback order; unidentified segments are present with status unknown so the timeline stays complete.

bash
curl https://ryser.id/api/public/sets/9c2e…

{ "id": "9c2e…", "url": "https://ryser.id/s/9c2e…", "title": "…", "uploader": "…",
  "source_url": "…", "duration_seconds": 5412, "identified_tracks": 31, "origin": "library",
  "finished_at": "2026-09-20T03:41:12.000Z",
  "tracks": [
    { "index": 0, "start_seconds": 0, "end_seconds": 318, "start": "0:00",
      "artist": "Da Capo", "title": "Kelaya", "status": "matched",
      "bpm": 122, "key": "F min",
      "artist_url": "https://ryser.id/artists/da-capo",
      "track_url": "https://ryser.id/tracks/da-capo-kelaya",
      "soundcloud_url": "https://soundcloud.com/search?q=Da%20Capo%20Kelaya",
      "beatport_search_url": "https://www.beatport.com/search?q=Da%20Capo%20Kelaya" },
    { "index": 1, "start_seconds": 318, "end_seconds": 611, "start": "5:18",
      "artist": "", "title": "", "status": "unknown", "bpm": 124, "key": null, … },
    …
  ] }

404 { "error": "not a public set" } when the id does not exist, is private, or is still running.

GET/api/public/artists/{slug}no key

A canonical artist. The slug is the lowercase hyphenated name (black-coffee, amelie-lens); the same slug is in every artist_url a tracklist row carries. Spelling variants and aliases resolve to the same artist, so the counts here include every way the name was heard.

bash
curl https://ryser.id/api/public/artists/black-coffee

{ "slug": "black-coffee", "name": "Black Coffee", "url": "https://ryser.id/artists/black-coffee",
  "links": { "instagram": "https://www.instagram.com/…", "spotify": "…", "soundcloud": "…", "youtube": null, "website": null },
  "identified_tracks": 142, "played_in_sets": 37,
  "top_tracks": [ { "artist": "Black Coffee", "title": "Wish You Were Here", "plays": 9 }, … ],
  "sets_performed": [ { …set summary… }, … ],   // sets this artist played (max 20)
  "played_in":      [ { …set summary… }, … ] }  // sets where their records were heard (max 20)

404 { "error": "unknown artist" } for a slug that is not a canonical artist yet.

GET/api/public/tracks/{slug}no key

A canonical record: the versions that were heard (original, remixes, edits, extended mixes) and every public set it appears in, with the position. Slug is artist-title without the version tag, as in every track_url a tracklist row carries.

bash
curl https://ryser.id/api/public/tracks/da-capo-kelaya

{ "slug": "da-capo-kelaya", "title": "Kelaya", "artist": "Da Capo",
  "url": "https://ryser.id/tracks/da-capo-kelaya",
  "artist_url": "https://ryser.id/artists/da-capo",
  "versions": [
    { "artist": "Da Capo", "title": "Kelaya", "version": "Original", "plays": 12 },
    { "artist": "Da Capo", "title": "Kelaya (Extended Mix)", "version": "Extended Mix", "plays": 4 } ],
  "appears_in": [
    { …set summary…, "at_seconds": 2711, "at": "45:11" },
    …
  ] }

404 { "error": "unknown track" } for a slug that is not a canonical track yet.

GET/api/public/tracklist?url={set link}no key

Built for the browser extension: given the link of the page a person is on, is there a public tracklist? It returns a compact list without the per-row links and is meant for showing a tracklist under a player, not for crawling. For anything else use the endpoints above.

bash
curl "https://ryser.id/api/public/tracklist?url=https://www.youtube.com/watch?v=…"

200 { "found": true, "run_id": "9c2e…", "url": "https://ryser.id/s/9c2e…", "title": "…", "uploader": "…",
      "duration": 5412, "identified": 31, "total": 34,
      "tracks": [ { "start": 0, "artist": "Da Capo", "title": "Kelaya", "bpm": 122, "key": "F min" }, … ] }
404 { "found": false, "analyse_url": "https://ryser.id/?url=…" }

Objects

The set summary is the same shape everywhere it appears: search results, an artist's sets, a track's appearances.

idstring (uuid)Stable id of the analysis. Use it with /api/public/sets/{id}.
urlstringPublic page on ryser.id.
title / uploaderstring | nullTitle and channel or profile as published on the source platform.
source_urlstring | nullCanonical link of the set on YouTube, SoundCloud or Mixcloud.
duration_secondsinteger | nullLength of the audio.
identified_tracksintegerRows with status matched.
originlibrary | communitylibrary: scanned automatically by ryser.id from a followed channel, not checked by a person yet. community: analysed by a person and shared.
finished_atISO datetime | nullWhen the analysis completed.

A tracklist row:

indexintegerPosition in the set, from 0.
start_seconds / end_secondsnumber | nullWhere the segment starts and ends in the audio. end_seconds can be null on the last row.
startstringstart_seconds formatted for display.
artist / titlestringEmpty strings when the row is unknown.
statusmatched | unknown | uncertainmatched: identified and corroborated. uncertain: one source named it and nothing confirmed it; show it as a guess. unknown: heard, not identified.
bpm / keynumber | null, string | nullTempo and musical key measured from the audio, per segment; present on unknown rows too when measurable.
artist_url / track_urlstringCanonical artist and track pages on ryser.id.
soundcloud_url / beatport_search_urlstring | nullSearch links for the record on those platforms.

Code examples

Plain fetch, no client library, no key.

javascript
// Node 18+, Deno, Bun, a browser, or a Next.js server component
async function tracklist(setId) {
  const res = await fetch(`https://ryser.id/api/public/sets/${setId}`);
  if (res.status === 404) return null;            // private, running or unknown
  if (!res.ok) throw new Error(`ryser.id ${res.status}: ${(await res.json()).error}`);
  return res.json();
}

const set = await tracklist("9c2e…");
for (const t of set.tracks) {
  console.log(t.start, t.status === "matched" ? `${t.artist} – ${t.title}` : "(unknown)");
}
python
import requests

def find_by_link(url: str):
    r = requests.get("https://ryser.id/api/public/search", params={"url": url}, timeout=20)
    if r.status_code == 404:
        return None                      # r.json()["analyse_url"] sends someone to analyse it
    r.raise_for_status()
    return r.json()["set"]

def artist(slug: str):
    r = requests.get(f"https://ryser.id/api/public/artists/{slug}", timeout=20)
    r.raise_for_status()
    return r.json()

s = find_by_link("https://www.youtube.com/watch?v=…")
if s:
    print(s["title"], s["identified_tracks"], "tracks", s["url"])
bash
# A one-liner for the terminal: every matched row of a set, its start, artist and title
curl -s https://ryser.id/api/public/sets/9c2e… \
  | jq -r '.tracks[] | select(.status=="matched") | "\(.start)\t\(.artist) – \(.title)"'

Limits and errors

Read endpoints60 requests per minute per address. Cached five minutes. Max 50 results per call.
Extension endpointMeant for one request per page view from the extension. Use the other endpoints for anything else.

Errors are JSON with one field:

json
{ "error": "Slow down: 60 requests per minute per address." }
400bad requestA missing or malformed url where one is needed.
404not foundNot a public set, unknown artist or track, or no tracklist for that link yet.
429too many requestsRate limit hit. Wait for the next minute.

Beta. Endpoints and field names are stable; new fields may appear without notice, so tolerate unknown keys. Questions, wishes, higher limits: [email protected]. Want an assistant to do this for you instead? See the MCP server.