Free API · v1

Build with artist headers.

Resolve Apple Music artist pages into structured logo, HLS, MP4, and resolution data with simple caller identification headers.

Base URLhttp://localhost:3000Replace this with your deployed Headliner URL in production.

AUTH

Request headers

Public v1 endpoints require the caller to identify their email and application. There are no API keys, accounts, or email-verification tokens.

X-Client-Email: developer@example.com
User-Agent: LRCGlass/1.0
Accept: application/json

Set HEADLINER_API_CLIENTS on the server to a comma-separated list of approved application User-Agent values.

GET

/api/v1/artists/search

Search Apple Music artists by name. Results include modern Apple Music artist URLs.

/api/v1/artists/search?q=alex%20warren

Response

{
  "success": true,
  "data": {
  "query": "alex warren",
  "count": 1,
  "results": [{
    "artistId": "1572671688",
    "artistName": "Alex Warren",
    "artistViewUrl": "https://music.apple.com/nl/artist/alex-warren/1572671688",
    "primaryGenreName": "Pop"
  }]
  },
  "error": null,
  "meta": { "api_version": "v1" }
}

GET

/api/v1/extract/artist

Inspect an Apple Music artist page and return the best available assets and every discovered video variant.

/api/v1/extract/artist?url=https%3A%2F%2Fmusic.apple.com%2Fnl%2Fartist%2Falex-warren%2F1572671688

Important response fields

headerVideo: Best HLS header, preferring the highest-resolution 16:9 rendition.
headerVideoMp4: Direct MP4 fallback when Apple exposes a single-file stream.
variants[]: Resolution, ratio, codec, HLS URL, and MP4 URL for each rendition.
ratioCheck: Whether a 16:9 variant was found and which resolution was chosen.

GET

/api/v1/health

Public health check. Authentication headers are not required.

GET

/api/v1/status

Public service status. Authentication headers are not required.

GET

/api/v1/albums/search

Search Apple Music albums by album or artist name.

/api/v1/albums/search?q=wildchild

GET

/api/v1/extract/album

Discover animated MP4/HLS artwork, verify square dimensions when metadata is available, and return a static artwork fallback.

/api/v1/extract/album?url=APPLE_MUSIC_ALBUM_URL

GET

/api/media

Proxy an Apple-hosted HLS playlist or media file. Playlists are rewritten so playback requests remain same-origin.

/api/media?url=APPLE_MEDIA_URL

GET

/api/download

Download an MP4 or assemble a supported HLS stream into a downloadable file.

/api/download?url=APPLE_MEDIA_URL&name=artist&label=3840x2160

Responsible use

Cache responses where possible, avoid high-volume polling, and respect Apple Music and CDN terms. Invalid requests use the consistent success, data, error, and meta response shape.