Developer API

Setlists, programmatically.

Queue analyses and fetch identified tracklists over plain HTTPS. Available on Pro — create keys under Account → API.

Authentication

Every request carries your key as a bearer token. Keys start with rysk_ and are shown once at creation — only a hash is stored.

curl https://ryser.id/api/v1/runs \
  -H "Authorization: Bearer rysk_your_key_here"

POST/api/v1/runs

Queue an analysis of a YouTube, SoundCloud or Mixcloud set. Costs 1 credit per minute of audio, like the web app. If a public analysis of the same URL already exists you get a free copy back instantly (duplicate: true, status done).

curl -X POST https://ryser.id/api/v1/runs \
  -H "Authorization: Bearer rysk_…" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=…"}'

# → 201 {"run_id": "1f0c…", "status": "queued"}

GET/api/v1/runs/{id}

Status and full setlist. Poll until status is done (or failed) — a 60-minute set typically takes 6–10 minutes. Unidentified segments come back with status: "unknown" and null artist/title.

{
  "id": "1f0c…", "status": "done",
  "title": "Boiler Room: …", "duration_seconds": 3612,
  "matched_tracks": 24, "total_tracks": 27,
  "tracks": [
    { "index": 0, "start_seconds": 0, "end_seconds": 312,
      "artist": "…", "title": "…", "status": "matched",
      "bpm": 128, "key": "A min", "provider": "shazam" },
    …
  ]
}

GET/api/v1/runs

Your 50 most recent runs, newest first.

Limits & errors

30 runs per 10 minutes per account (shared with the web app), max 5 active keys.
401 bad key · 402 out of credits · 403 no active Pro · 429 rate limited · 503 worker offline (retry).
Errors are JSON: {"error": "…"}.

The API is in beta — endpoints are stable, fields may be added. Questions or wishes: [email protected].