verification
use it
# add to stunt.yaml
services:
apple-music:
adapter: embedded:apple-music-style
# then
$ stunt upThe embedded: source extracts this adapter from the binary — no git clone, fully offline.
how to mock the Apple Music API locally
Install stunt, paste the service block above into stunt.yaml, run stunt up — then point your client at localhost instead of Apple Music API. It works offline, keeps state across requests and restarts, and every response is synthetic: the route shapes, status codes, pagination, and webhook delivery follow the real Apple Music API 1.0 surface — the data is fake, the behavior is real.
backing stores
songsalbumslibrary_songs
api surface (18)
generated from the adapter manifest — exactly what boots, nothing more
18 routes
GET/v1/catalog/{storefront}/search
GET/v1/catalog/{storefront}/charts
GET/v1/catalog/{storefront}/songs
GET/v1/catalog/{storefront}/albums
GET/v1/catalog/{storefront}/artists
GET/v1/catalog/{storefront}/playlists
GET/v1/catalog/{storefront}/songs/{id}
GET/v1/catalog/{storefront}/albums/{id}
GET/v1/catalog/{storefront}/artists/{id}
GET/v1/me/library/songs
GET/v1/me/library/albums
GET/v1/me/library/playlists
GET/v1/me/library/recently-added
POST/v1/me/library
DELETE/v1/me/library/{type}/{id}
POST/v1/me/played
GET/v1/me/ratings/{type}/{id}
PUT/v1/me/ratings/{type}/{id}
VM-verified behaviors (24)
- ✓a missing bearer answers 401 in Apple's error envelope
- ✓malformed schemes, segments, algs and signatures are all 401
- ✓the registered deterministic developer token reads the catalog
- ✓the developer token dies when its registry entry expires
- ✓search without a term is a 400 invalid_parameter
- ✓results group by requested type in meta order with next links
- ✓the term matches names, artists and album text case-insensitively
- ✓unknown search and chart types are 400 invalid_parameter
- ✓charts order the seed by release date within each requested type
- ✓include=tracks embeds track resources; without it only an href
- ✓storefront codes are validated and normalized (US -> us)
- ✓unknown ids answer Apple's 404 error body
- ✓a known album and artist fetch with storefront-derived hrefs
- ✓pages walk by offset and the last partial page has no next
- ✓limits clamp to the endpoint default and max
- ✓library lists page with meta.total
- ✓/v1/me checks the developer JWT before the Music-User-Token
- ✓adding resources to the library is idempotent and validates ids
- ✓played bumps playCount and stamps lastPlayedDate at play time
- ✓recently-added lists newest first across mixed resource types
- ✓fields[type] projects library attributes
- ✓delete addresses the catalog id or the library id, then 404s
- ✓an unrated resource reads 0; love/dislike/clear round-trip
- ✓invalid values and unknown targets keep the documented shapes
Not implemented (5)
- No music-videos, stations, genres, or curators catalog endpoints
- No storefronts endpoint (GET /v1/storefronts)
- No library search (GET /v1/me/library/search)
- No personal playlist create or add-tracks (POST /v1/me/library/playlists)
- No recommendations or play history (heavy-rotation, recent/played)
Differs from the real API (5)
- Developer JWT signature not verified — structural check plus exact-string token registry
- Music-User-Token accepts any non-empty value — no real user-token validation
- Only registered developer tokens pass the gate; real Apple accepts any properly signed ES256 token
- Storefront codes are validated but do not scope the catalog (gb == us)
- Library lists carry a meta.total the real API does not return
want more of the Apple Music API surface? adapters are YAML + Starlark — the authoring guide covers adding routes, fixtures, and state machines. Open an issue for anything big first, or just file a PR — merged routes ship in the next release.