Main/docs/api.md

# API Reference

Shanty exposes a REST API at `/api/*` and a Subsonic-compatible API at `/rest/*`. All REST endpoints require authentication via session cookie unless noted otherwise.

## Authentication

All `/api/*` endpoints (except the auth endpoints listed below) require an active session. To authenticate, call the login endpoint and include the returned session cookie in subsequent requests.

### Endpoints

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/auth/setup-required` | No | Check if initial setup is needed (returns `{"required": true}` if no users exist) |
| POST | `/api/auth/setup` | No | Create the first admin user. Only works when no users exist. Body: `{"username": "...", "password": "..."}` |
| POST | `/api/auth/login` | No | Log in. Body: `{"username": "...", "password": "..."}`. Returns user info and sets session cookie. |
| POST | `/api/auth/logout` | Yes | Log out and clear session. |
| GET | `/api/auth/me` | Yes | Get current user info (id, username, role). |
| GET | `/api/auth/users` | Admin | List all users. |
| POST | `/api/auth/users` | Admin | Create a new user. Body: `{"username": "...", "password": "..."}` |
| DELETE | `/api/auth/users/{id}` | Admin | Delete a user. Cannot delete yourself. |
| PUT | `/api/auth/subsonic-password` | Yes | Set Subsonic password for current user. Body: `{"password": "..."}` |
| GET | `/api/auth/subsonic-password-status` | Yes | Check if current user has a Subsonic password set. |

---

## Artists

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/artists` | Yes | List all artists in the library. Supports `?limit=50&offset=0` pagination. Returns artist names, MBIDs, monitored status, and track counts (watched/owned/total). |
| POST | `/api/artists` | Yes | Add (watch) an artist. Body: `{"name": "...", "mbid": "..."}`. At least one of name or mbid is required. Expands the artist's full discography into individual track wanted_items. |
| GET | `/api/artists/{id}` | Yes | Get artist by local database ID. Returns artist info and local albums. |
| GET | `/api/artists/{id}/full` | Yes | Get full artist detail with MusicBrainz enrichment. Accepts local ID or MBID. Returns discography with per-album status (owned/partial/wanted/unwatched), artist photo, bio, and banner. Supports `?quick=true` to skip per-album track fetches. |
| DELETE | `/api/artists/{id}` | Admin | Delete an artist from the library. |
| POST | `/api/artists/{id}/monitor` | Yes | Enable monitoring for an artist. |
| DELETE | `/api/artists/{id}/monitor` | Yes | Disable monitoring for an artist. |

---

## Albums

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/albums` | Yes | List all local albums. Supports `?limit=50&offset=0`. |
| POST | `/api/albums` | Yes | Add (watch) an album. Body: `{"artist": "...", "album": "...", "mbid": "..."}`. Accepts release or release-group MBID. Expands to individual track wanted_items. |
| GET | `/api/albums/{mbid}` | Yes | Get album track listing by MBID (release or release-group). Returns tracks with per-track status. |

---

## Tracks

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/tracks` | Yes | List tracks. Supports `?limit=50&offset=0` and `?q=search` for text search. |
| GET | `/api/tracks/{id}` | Yes | Get a single track by local database ID. |

---

## Search

Search queries MusicBrainz (either the local database or the remote API).

| Method | Path | Auth | Parameters | Description |
|--------|------|------|------------|-------------|
| GET | `/api/search/artist` | Yes | `q` (required), `limit` (default 25) | Search for artists by name. Returns MBID, name, disambiguation. |
| GET | `/api/search/album` | Yes | `q` (required), `artist` (optional), `limit` (default 25) | Search for albums. |
| GET | `/api/search/track` | Yes | `q` (required), `artist` (optional), `limit` (default 25) | Search for tracks. |
| GET | `/api/search/discography/{mbid}` | Yes | (none) | Get an artist's full discography (release groups) by MBID. |

---

## Downloads

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/downloads/queue` | Yes | List download queue. Optional `?status=pending\|downloading\|completed\|failed\|cancelled`. |
| POST | `/api/downloads` | Yes | Enqueue a manual download. Body: `{"query": "..."}`. |
| POST | `/api/downloads/sync` | Yes | Sync wanted items to download queue. Returns count of found/enqueued/skipped. |
| POST | `/api/downloads/process` | Yes | Start processing the download queue (background task). Returns a task_id. |
| POST | `/api/downloads/retry/{id}` | Yes | Requeue a failed download. |
| DELETE | `/api/downloads/{id}` | Yes | Cancel a download. |

---

## Playlists

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/api/playlists/generate` | Yes | Generate a playlist (preview, not saved). Body includes strategy, seed_artists, count, etc. |
| GET | `/api/playlists` | Yes | List saved playlists for the current user. |
| POST | `/api/playlists` | Yes | Save a playlist. Body: `{"name": "...", "description": "...", "track_ids": [1, 2, 3]}` |
| GET | `/api/playlists/{id}` | Yes | Get a playlist with its tracks. |
| PUT | `/api/playlists/{id}` | Yes | Update playlist name/description. Body: `{"name": "...", "description": "..."}` |
| DELETE | `/api/playlists/{id}` | Yes | Delete a playlist. |
| GET | `/api/playlists/{id}/m3u` | Yes | Export playlist as M3U file download. |
| POST | `/api/playlists/{id}/tracks` | Yes | Add a track. Body: `{"track_id": 123}` |
| PUT | `/api/playlists/{id}/tracks` | Yes | Reorder tracks. Body: `{"track_ids": [3, 1, 2]}` |
| DELETE | `/api/playlists/{id}/tracks/{track_id}` | Yes | Remove a track from the playlist. |

### Playlist Generation Body

```json
{
  "strategy": "similar",
  "seed_artists": ["Pink Floyd", "Radiohead"],
  "count": 50,
  "popularity_bias": 0.5,
  "ordering": "interleave",
  "genres": [],
  "rules": []
}
```

Strategies: `similar`, `genre`, `random`, `smart`.
Ordering options: `interleave`, `score`, `random`.

---

## Lyrics

| Method | Path | Auth | Parameters | Description |
|--------|------|------|------------|-------------|
| GET | `/api/lyrics` | Yes | `artist` (required), `title` (required) | Fetch lyrics from LRCLIB. Returns plain lyrics and time-synced lyrics if available. Cached for 30 days. |

---

## System and Pipeline

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/status` | Yes | Dashboard status: library summary, download queue, tagging queue, active tasks, scheduler info. |
| POST | `/api/pipeline` | Yes | Trigger the full pipeline (sync + download + tag + organize). Returns task_ids. |
| POST | `/api/index` | Yes | Trigger a library scan (background task). |
| POST | `/api/tag` | Yes | Trigger tagging of untagged tracks (background task). |
| POST | `/api/organize` | Yes | Trigger file organization (background task). |
| GET | `/api/tasks/{id}` | Yes | Get task status (running/completed/failed, progress, message). |

---

## Watchlist

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/watchlist` | Yes | List wanted items for the current user. |
| DELETE | `/api/watchlist/{id}` | Yes | Remove a wanted item. |

---

## YouTube Authentication

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/ytauth/status` | Yes | Get YouTube auth status: authenticated, cookie age, refresh status, yt-dlp version, API key status. |
| POST | `/api/ytauth/login-start` | Admin | Launch Firefox + noVNC for interactive YouTube login. Returns VNC URL. |
| POST | `/api/ytauth/login-stop` | Admin | Stop Firefox, export cookies, enable auto-refresh. |
| POST | `/api/ytauth/refresh` | Admin | Trigger immediate headless cookie refresh. |
| DELETE | `/api/ytauth/cookies` | Admin | Clear all cookies and Firefox profile, disable refresh. |

---

## Monitor

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/api/monitor/check` | Admin | Trigger an immediate check of all monitored artists for new releases. |
| GET | `/api/monitor/status` | Yes | List all monitored artists with last check timestamps. |

---

## Scheduler

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/api/scheduler/skip-pipeline` | Admin | Skip the next scheduled pipeline run. |
| POST | `/api/scheduler/skip-monitor` | Admin | Skip the next scheduled monitor check. |

---

## MusicBrainz

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/mb-status` | Yes | Check if local MusicBrainz database is available and get stats (artist/release/recording counts). |
| POST | `/api/mb-import` | Admin | Trigger MusicBrainz database import (background task). Downloads dumps and imports. |

---

## Config

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/config` | Yes | Get current configuration. |
| PUT | `/api/config` | Admin | Update configuration. Body is the full AppConfig JSON object. Writes to YAML file and updates in-memory config. |

---

## Subsonic API

The Subsonic API is served at `/rest/*` and uses the Subsonic authentication protocol (username + MD5 token or plaintext password, passed as query parameters).

All Subsonic endpoints accept the standard Subsonic query parameters: `u` (username), `p` (password or `enc:` hex-encoded), `t` (MD5 token), `s` (salt), `v` (API version), `c` (client name), `f` (response format, defaults to XML).

Each endpoint is available at both `/rest/endpoint` and `/rest/endpoint.view`.

### System

| Path | Description |
|------|-------------|
| `/rest/ping` | Server health check. |
| `/rest/getLicense` | Returns license status (always valid). |

### Browsing

| Path | Description |
|------|-------------|
| `/rest/getMusicFolders` | List music library folders. |
| `/rest/getIndexes` | Get alphabetical artist index. |
| `/rest/getMusicDirectory` | Get contents of a directory (artist's albums or album's tracks). Parameter: `id`. |
| `/rest/getArtists` | Get all artists (ID3 tag based). |
| `/rest/getArtist` | Get an artist with albums. Parameter: `id`. |
| `/rest/getAlbum` | Get an album with tracks. Parameter: `id`. |
| `/rest/getSong` | Get a single track. Parameter: `id`. |
| `/rest/getGenres` | List all genres. |

### Search

| Path | Description |
|------|-------------|
| `/rest/search3` | Search artists, albums, and tracks. Parameters: `query`, `artistCount`, `albumCount`, `songCount`, `artistOffset`, `albumOffset`, `songOffset`. |

### Media

| Path | Description |
|------|-------------|
| `/rest/stream` | Stream an audio file. Parameter: `id`. Transcodes Opus to MP3 if transcoding is enabled. |
| `/rest/download` | Download an audio file (original format). Parameter: `id`. |
| `/rest/getCoverArt` | Get cover art image. Parameter: `id`. |

### Playlists

| Path | Description |
|------|-------------|
| `/rest/getPlaylists` | List all playlists. |
| `/rest/getPlaylist` | Get a playlist with tracks. Parameter: `id`. |
| `/rest/createPlaylist` | Create or update a playlist. Parameters: `name`, `songId` (repeatable). |
| `/rest/deletePlaylist` | Delete a playlist. Parameter: `id`. |

### Annotation

| Path | Description |
|------|-------------|
| `/rest/scrobble` | Record a play. Parameters: `id`, `submission` (true/false). |

### User

| Path | Description |
|------|-------------|
| `/rest/getUser` | Get user details. Parameter: `username`. |