# Hep.gg Music API

Download tracks by ISRC, search the catalog, mirror YouTube / SoundCloud URLs.
Auth is a single per-user API key.

Worker base URL: https://music.jakeypri.me
Auth: ?key=<your-key> OR Authorization: <your-key> OR X-API-Key: <your-key>

## Endpoints

### GET /download?isrc=<ISRC>&quality=<128|320|flac>
Returns the audio file. Quality defaults to 320.
  isrc      string   12-char ISRC. Required.
  quality   string   '128', '320', or 'flac'. Default '320'.
Headers: streams audio/mpeg or audio/flac with Content-Disposition: attachment.

### GET /yt?url=<youtube-url>
Best-effort YouTube -> mp3 via Deezer ISRC matching when available; falls back
to a youtube-dl-equivalent extractor. Returns audio/mpeg.

### GET /soundcloud?url=<soundcloud-url>
Same shape for SoundCloud tracks.

### GET /search?q=<query>&limit=<n>
Search the catalog. Returns JSON list of hits with ISRC, artist, title, etc.

### GET /searchfull?q=<query>
Extended search that includes album / track metadata.

### GET /stream/:isrc
Stream a track. Used internally by the profile audio embed. Requires the same
auth as /download.

### GET /artwork/:isrc
Cover art proxy. Unauthenticated.

## Quotas
Per-key counters in hep.gg.music_keys: song_count, youtube_count,
soundcloud_count, search_count. Users may hold 1 active key on free,
2 on Hep.gg Prime. Plan limits enforced on the API side.

## Hep.gg dashboard
  GET  /api/v1/music/account
  POST /api/v1/music/account/rotate
  GET  /api/v1/music/catalog?q=&limit=
  GET  /api/v1/music/stats