# Apple Music API > Sync a playlist to Apple Music using the Apple Music REST API. Faster and more reliable than browser automation. Requires Apple Developer credentials via environment variables. Use when the user wants to save or sync a playlist to Apple Music, add a playlist to their library, or export a playlist to Apple Music. Use when this capability is needed. - Skill: `tomevault-io/apple-music-api` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/apple-music-api` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/apple-music-api/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/apple-music-api --- # Apple Music API Sync Sync a playlist from this repository to Apple Music using the [Apple Music REST API](https://developer.apple.com/documentation/applemusicapi). No browser automation or Playwright required — all operations are pure HTTP API calls. ## When to Use This Skill Activate this skill when the user: - Wants to save a playlist to Apple Music - Asks to sync, export, or push a playlist to their library - Wants to create an Apple Music playlist from a markdown file - Mentions "Apple Music," "sync," or "add to my library" in the context of a playlist - Wants a headless/automated sync (CI, GitHub Agent tasks) **Prefer this skill over `apple-music-sync`** when environment variables are configured. Fall back to the browser-based `apple-music-sync` skill if credentials are not available. ## Prerequisites - **Apple Developer Program** membership - **MusicKit private key** (.p8 file) from the Apple Developer portal - **Apple Music subscription** for the user account - **Node.js** (v18+) ## Environment Variables All credentials are passed as environment variables (compatible with GitHub secrets): | Variable | Description | |----------|-------------| | `APPLE_MUSIC_TEAM_ID` | Your Apple Developer Team ID (10 characters) | | `APPLE_MUSIC_KEY_ID` | Your MusicKit private key ID (10 characters) | | `APPLE_MUSIC_PRIVATE_KEY` | Contents of your `.p8` private key file (including `BEGIN`/`END` lines) | | `APPLE_MUSIC_USER_TOKEN` | Music User Token obtained via MusicKit JS authorization | ### Obtaining Your Music User Token The Music User Token requires a one-time browser-based authorization flow using MusicKit JS. It lasts approximately 6 months. Run the included authorization helper: ```bash export APPLE_MUSIC_TEAM_ID="XXXXXXXXXX" export APPLE_MUSIC_KEY_ID="XXXXXXXXXX" export APPLE_MUSIC_PRIVATE_KEY="$(cat path/to/AuthKey_XXXXXXXXXX.p8)" node .github/skills/apple-music-api/authorize.mjs ``` This opens a local web page where you sign in to Apple Music. The token is printed to stdout — copy it and store it as `APPLE_MUSIC_USER_TOKEN`. When it expires (~6 months), run `authorize.mjs` again. ### Setting Up Locally ```bash # Option 1: Export directly export APPLE_MUSIC_TEAM_ID="XXXXXXXXXX" export APPLE_MUSIC_KEY_ID="XXXXXXXXXX" export APPLE_MUSIC_PRIVATE_KEY="$(cat path/to/AuthKey_XXXXXXXXXX.p8)" export APPLE_MUSIC_USER_TOKEN="your-music-user-token" # Option 2: Use a .env file (not committed — add to .gitignore) ``` ### Setting Up for GitHub Agent Tasks Add each variable as a repository secret in GitHub Settings → Secrets and Variables → Actions. ## Tools ### `sync.mjs` — Sync playlist to Apple Music ```bash # Sync a playlist (create if needed, or recreate to match markdown order) node .github/skills/apple-music-api/sync.mjs playlists/.md # Only add tracks to library (no playlist management) node .github/skills/apple-music-api/sync.mjs playlists/.md --library-only # Rename an existing playlist node .github/skills/apple-music-api/sync.mjs playlists/.md --rename-from="Old Name" ``` The script: 1. Parses the playlist name from the `# heading` and tracks from the markdown table 2. **Appends the 🤖 emoji** to the playlist name — all managed playlists are suffixed with this marker 3. **Creates a daily backup** before any sync operation (see Backups below) 4. Resolves all track IDs from Apple Music URLs in the markdown (or falls back to catalog search) 5. Creates a fresh playlist and adds all tracks in the correct order 6. Reports any tracks that couldn't be found or added **Playlist safety:** The script will only ever modify playlists that end with the 🤖 suffix. User-created playlists without this marker are never touched. ### Backups Before every sync, the script creates a backup by **renaming** the existing 🤖 playlist to ` 🔙 (yyyy-MM-dd)`. The sync then creates a fresh 🤖 playlist from scratch. **⚠️ Backups are immutable.** Once created, a backup must **NEVER** be modified, renamed, or deleted by automation. The `assertManaged` guard will throw an error if any operation attempts to touch a playlist containing the 🔙 marker. Only one backup per playlist per day is created; if today's backup already exists, it is skipped. ## Workflow ### Step 1: Check Environment Verify that all required environment variables are set. If any are missing, inform the user and suggest either setting them up or falling back to the browser-based `apple-music-sync` skill. ### Step 2: Identify the Playlist Determine which playlist markdown file to sync from the `playlists/` folder. ### Step 3: Run the Sync ```bash node .github/skills/apple-music-api/sync.mjs playlists/.md ``` The sync runs entirely via API calls — no browser window, no sign-in flow, no user interaction needed. It can be run headlessly in CI or GitHub Agent tasks. ### Step 4: Monitor Progress The script outputs progress to stdout: - Track resolution phase: shows each track being resolved from URL or search - Sync phase: shows album-by-album progress as tracks are added ### Step 5: Verify Ask the user to check the playlist in Apple Music. Confirm the track count and order look correct. ## Error Handling - If a track cannot be found in the Apple Music catalog, the script reports it and continues with the remaining tracks - If the Apple Music API returns rate-limiting errors (429), the script backs off and retries - Server errors (5xx) are retried with exponential backoff - The user may need to manually add tracks that the script couldn't find (e.g., region restrictions, name mismatches) - If environment variables are missing, the script fails immediately with a clear error message ## Differences from Browser-Based Skill | Feature | `apple-music-api` (this skill) | `apple-music-sync` (browser) | |---------|-------------------------------|-------------------------------| | Speed | Fast (API calls) | Slow (browser navigation) | | Reliability | High (no DOM scraping) | Medium (virtual scrolling, HTTP/2 errors) | | User interaction | None (fully automated) | Sign-in required on first use | | Headless | Always headless | Optional `--headless` flag | | Requirements | Apple Developer credentials | Just a browser | | CI/CD compatible | Yes (via secrets) | No | --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/jeffhandley) — claim your Tome and manage your conversions.