API Reference

Vynl exposes a REST API at /api/*. Same surface the web UI uses. No authentication required on the local network (assumes you're firewalling Vynl to trusted clients).

Status: OUTLINE — full reference + curl examples to be filled in. This file lists every endpoint by area; details for each come in a follow-up pass.

Conventions

• Base URL: http://your-vynl-host:3101
• Content-Type: application/json on POST/PUT
• Errors: JSON with { "error": "...", "details": "..." } and an HTTP status
• All timestamps are ISO 8601 in UTC

Endpoints by area

Library

• GET /api/albums — list albums (filterable, sortable, since-window)
• GET /api/albums/[id] — single album with tracks
• POST /api/albums/cover-update — set album cover from image URL
• POST /api/albums/cover-search — search cover providers
• POST /api/albums/rename — rename album + album artist
• GET /api/tracks/[id] — single track
• PUT /api/tracks/[id]/rating — set 1-5 star rating
• DELETE /api/tracks/[id]/rating — clear rating
• GET /api/library/duplicates — find duplicates
• POST /api/library/scan — trigger full scan
• POST /api/library/analyze-tracks — audio feature analysis (BPM/energy)
• GET /api/library/watcher — file watcher status
• PUT /api/library/watcher — save watcher config
• POST /api/library/watcher — start watcher
• DELETE /api/library/watcher — stop watcher

Playlists

• GET /api/playlists — list
• POST /api/playlists — create
• GET /api/playlists/[id] — single playlist with tracks
• PUT /api/playlists/[id] — update name/description/section
• DELETE /api/playlists/[id] — delete (will route through FireStorage in v0.7)
• POST /api/playlists/generate — AI-generated playlist from prompt
• POST /api/playlists/auto-generate — auto-generated mood/era playlists

Discovery

• POST /api/discover/session — start discovery session
• GET /api/discover/samples — get next batch of sample tracks
• POST /api/discover/feedback — submit like/dislike feedback

Player

• GET /api/audio/[...path] — stream audio file by path
• POST /api/listening-history — record a play
• GET /api/listening-history — read play history

Sonos

• GET /api/sonos/devices — discovered speakers
• POST /api/sonos/play — play track on room
• POST /api/sonos/pause
• POST /api/sonos/group

Podcasts

• GET /api/podcasts — list subscribed podcasts
• POST /api/podcasts — subscribe to a feed URL
• GET /api/podcasts/[id] — podcast with episodes
• DELETE /api/podcasts/[id] — unsubscribe (will route through FireStorage)
• GET /api/podcasts/[id]/episodes/[episodeId] — episode detail
• POST /api/podcasts/[id]/episodes/[episodeId]/download — download for offline

Spotify Migration

• POST /api/spotify/auth — kick off OAuth
• GET /api/spotify/callback — OAuth callback
• GET /api/spotify/status — connection state
• POST /api/spotify/migration/sync — start safe-phases sync
• GET /api/spotify/migration/snapshot — current snapshot summary
• GET /api/spotify/migration/playlists — Spotify playlists in snapshot
• GET /api/spotify/migration/tracks — tracks (joined with match state)
• POST /api/spotify/migration/wishlist — bulk-add to wishlist
• POST /api/spotify/migration/download — spotDL download
• POST /api/spotify/migration/create-playlist — mirror as Vynl playlist
• DELETE /api/spotify — disconnect + wipe

Wishlist

• GET /api/wishlist — list items
• POST /api/wishlist — add item
• DELETE /api/wishlist — bulk delete (will route through FireStorage)

Lidarr

• POST /api/lidarr/push — push wishlist items to Lidarr

Settings

• GET /api/settings/keys — list API key keys (values redacted)
• POST /api/settings/keys — set a key/value
• DELETE /api/settings/keys — clear a key (falls back to env)

FireStorage (v0.7+)

• GET /api/firestorage — list held entries
• POST /api/firestorage/[id]/restore — instant restore
• POST /api/firestorage/[id]/purge — hard delete (2FA required once available)

Covers / images

• GET /api/covers/[filename] — serve album cover by hash filename
• GET /api/artist-images/[filename] — serve artist image

Stats

• GET /api/stats/overview — track/album/artist counts, top genres, listening totals

Next steps for this doc

• Add request/response schemas for each endpoint
• Add curl examples for the 20 most-used endpoints
• Add OpenAPI / Swagger generation from route handlers
• Add rate-limit notes where applicable