### GET /api/settings

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Retrieves current application settings.

```APIDOC
## GET /api/settings

### Description
Retrieves current application settings with a preview of the file naming template.

### Method
GET

### Endpoint
/api/settings
```

--------------------------------

### Development Commands

Source: https://github.com/crashed6767/spotitoflac/blob/claude/spotify-to-flac-converter-80mQs/CLAUDE.md

Commands for installing dependencies and running the development environment for the monorepo.

```bash
npm install          # Install all dependencies
npm run dev          # Start both server and client
npm run dev:server   # Server only (port 3001)
npm run dev:client   # Client only (port 5173)
```

--------------------------------

### Get All Settings

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Fetches current application settings and a preview of the file naming template.

```bash
curl -X GET "http://localhost:3001/api/settings" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### GET /api/status

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Returns comprehensive system health information.

```APIDOC
## GET /api/status

### Description
Returns comprehensive system health information including dependencies, queue state, and resource usage.

### Method
GET

### Endpoint
/api/status
```

--------------------------------

### Get Overview KPIs

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Fetches high-level statistics including download counts, success rates, storage usage, and monitoring status.

```bash
curl -X GET "http://localhost:3001/api/analytics/overview" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Start Multiple Downloads

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Initiate downloads for multiple tracks by providing their IDs and an optional playlist ID and format. The server will queue these tracks for download.

```bash
curl -X POST "http://localhost:3001/api/downloads" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "trackIds": ["4PTG3Z6ehGkBFwjybzWkR8", "7qiZfU4dY1lWllzX7mPBI3"],
    "playlistId": "37i9dQZF1DXcBWIGoYBM5M",
    "format": "flac"
  }'
```

--------------------------------

### GET /api/downloads/queue

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Returns the current download queue state.

```APIDOC
## GET /api/downloads/queue

### Description
Returns the current download queue state with counts of queued and active downloads.

### Method
GET

### Endpoint
/api/downloads/queue

### Response
#### Success Response (200)
- **queued** (integer) - Number of queued items
- **active** (integer) - Number of active items
- **maxConcurrent** (integer) - Maximum concurrent downloads allowed

#### Response Example
{
  "queued": 5,
  "active": 2,
  "maxConcurrent": 3
}
```

--------------------------------

### Get System Status

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Returns health information, including queue state and resource usage.

```bash
curl -X GET "http://localhost:3001/api/status" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Get Release Statistics

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Returns daily new release discovery statistics for the past 30 days, including total and downloaded counts.

```bash
curl -X GET "http://localhost:3001/api/analytics/releases" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Get Top Artists by Downloads

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Returns artists ranked by download count along with the total storage used per artist. A limit parameter can be specified.

```bash
curl -X GET "http://localhost:3001/api/analytics/artists?limit=20" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### GET /api/artists/releases/new

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Retrieves recent releases from all monitored artists.

```APIDOC
## GET /api/artists/releases/new

### Description
Retrieves recent releases from all monitored artists within a specified time period.

### Method
GET

### Endpoint
/api/artists/releases/new

### Parameters
#### Query Parameters
- **days** (integer) - Optional - Number of days to look back (default: 7)

### Response
#### Success Response (200)
- Returns a list of release objects.
```

--------------------------------

### Get Format Breakdown

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Retrieves download statistics grouped by audio format, including count and total bytes.

```bash
curl -X GET "http://localhost:3001/api/analytics/formats" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### GET /api/artists

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Retrieves all artists being monitored for new releases.

```APIDOC
## GET /api/artists

### Description
Retrieves all artists being monitored for new releases with release statistics.

### Method
GET

### Endpoint
/api/artists

### Response
#### Success Response (200)
- **id** (string) - Artist ID
- **name** (string) - Artist name
- **spotify_url** (string) - Spotify URL
- **image_url** (string) - Image URL
- **release_count** (integer) - Total releases found
- **downloaded_count** (integer) - Total releases downloaded
- **next_check_at** (string) - Timestamp of next check

#### Response Example
[
  {
    "id": "abc123",
    "name": "Sabrina Carpenter",
    "spotify_url": "https://open.spotify.com/artist/74KM79TiuVKeVCqs8QtB0B",
    "image_url": "https://i.scdn.co/image/...",
    "release_count": 15,
    "downloaded_count": 12,
    "next_check_at": "2024-01-15T14:00:00.000Z"
  }
]
```

--------------------------------

### Get Downloads Over Time

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Retrieves daily download statistics for charting trends over configurable time periods. Defaults to the last 30 days.

```bash
# Get last 30 days (default)
curl -X GET "http://localhost:3001/api/analytics/downloads" \
  -H "Authorization: Bearer $TOKEN"
```

```bash
# Get last 7 days
curl -X GET "http://localhost:3001/api/analytics/downloads?period=7d" \
  -H "Authorization: Bearer $TOKEN"
```

```bash
# Get last 90 days
curl -X GET "http://localhost:3001/api/analytics/downloads?period=90d" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Get Activity Heatmap

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Returns download activity grouped by day of the week and hour, suitable for visualization.

```bash
curl -X GET "http://localhost:3001/api/analytics/activity" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### GET /api/downloads

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Retrieves a list of download records with support for pagination and filtering.

```APIDOC
## GET /api/downloads

### Description
Retrieves download records with optional filtering by status and playlist. Includes queue status information.

### Method
GET

### Endpoint
/api/downloads

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Number of records to return
- **offset** (integer) - Optional - Number of records to skip
```

--------------------------------

### Get Single Playlist Details

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Retrieves detailed information for a specific playlist, including track lists and download statuses.

```bash
# Get playlist details with tracks
curl -X GET "http://localhost:3001/api/playlists/37i9dQZF1DXcBWIGoYBM5M" \
  -H "Authorization: Bearer $TOKEN"

# Response
{
  "id": "37i9dQZF1DXcBWIGoYBM5M",
  "name": "Today's Top Hits",
  "owner": "Spotify",
  "track_count": 50,
  "tracks": [
    {
      "id": "4PTG3Z6ehGkBFwjybzWkR8",
      "position": 1,
      "name": "Espresso",
      "artist": "Sabrina Carpenter",
      "album": "Espresso",
      "duration_ms": 175459,
      "isrc": "USUM72404062",
      "download": {
        "id": 123,
        "status": "completed",
        "file_path": "/downloads/Sabrina Carpenter/Espresso/01 - Espresso.flac",
        "file_size": 28456789,
        "quality_verified": 1
      },
      "also_in": ["Summer Vibes 2024", "Pop Hits"]
    }
  ]
}
```

--------------------------------

### GET /ws

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Connects to the WebSocket endpoint for real-time download progress and event notifications.

```APIDOC
## GET /ws

### Description
Connects to the WebSocket endpoint for real-time download progress and event notifications.

### Method
GET

### Endpoint
/ws

### Parameters
#### Query Parameters
- **token** (string) - Required - Authentication token
```

--------------------------------

### POST /api/downloads/{id}/cancel

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Cancels a queued download before it starts processing.

```APIDOC
## POST /api/downloads/{id}/cancel

### Description
Cancels a queued download before it starts processing.

### Method
POST

### Endpoint
/api/downloads/{id}/cancel

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the queued download

### Response
#### Success Response (200)
- **ok** (boolean) - Confirmation status

#### Response Example
{ "ok": true }
```

--------------------------------

### Get New Releases (Last 7 Days)

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Fetch new releases from all monitored artists within the last 7 days. This is the default time period if no `days` parameter is specified.

```bash
curl -X GET "http://localhost:3001/api/artists/releases/new" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Get Weekly Digest Preview

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Retrieves a digest of all releases discovered in the past week. Useful for generating weekly summaries.

```bash
curl -X GET "http://localhost:3001/api/artists/digest" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### GET /api/logs

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Searches and filters logs from the SQLite database for historical analysis.

```APIDOC
## GET /api/logs

### Description
Searches and filters logs from the SQLite database for historical analysis.

### Method
GET

### Endpoint
/api/logs

### Parameters
#### Query Parameters
- **level** (string) - Optional - Filter by log level (e.g., error)
- **source** (string) - Optional - Filter by log source
- **limit** (integer) - Optional - Maximum number of logs to return
- **search** (string) - Optional - Text search query
- **startDate** (string) - Optional - Start date for filtering
- **endDate** (string) - Optional - End date for filtering

### Response
#### Success Response (200)
- **logs** (array) - List of log objects
- **total** (integer) - Total count of logs matching criteria

#### Response Example
{
  "logs": [
    {
      "id": 12345,
      "timestamp": "2024-01-15T10:25:00.000Z",
      "level": "error",
      "source": "downloader",
      "message": "Failed: Artist - Track Name",
      "meta": "{\"downloadId\": 455, \"error\": \"Network timeout\"}"
    }
  ],
  "total": 78
}
```

--------------------------------

### GET /api/downloads

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Retrieves a list of downloads, optionally filtered by status or playlist ID.

```APIDOC
## GET /api/downloads

### Description
Retrieves a list of downloads, optionally filtered by status or playlist ID.

### Method
GET

### Endpoint
/api/downloads

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filter by status (queued, downloading, completed, failed)
- **limit** (integer) - Optional - Limit the number of results
- **playlist_id** (string) - Optional - Filter by playlist ID

### Response
#### Success Response (200)
- **downloads** (array) - List of download objects
- **total** (integer) - Total count of downloads
- **queue** (object) - Current queue state

#### Response Example
{
  "downloads": [
    {
      "id": 456,
      "track_id": "4PTG3Z6ehGkBFwjybzWkR8",
      "playlist_id": "37i9dQZF1DXcBWIGoYBM5M",
      "status": "completed",
      "format": "flac",
      "file_path": "/downloads/Artist/Album/01 - Track.flac",
      "file_size": 28456789,
      "quality_verified": 1,
      "track_name": "Espresso",
      "artist": "Sabrina Carpenter",
      "playlist_name": "Today's Top Hits"
    }
  ],
  "total": 156,
  "queue": { "queued": 5, "active": 2, "maxConcurrent": 3 }
}
```

--------------------------------

### GET /api/search

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Performs a unified search across playlists, tracks, artists, and downloads.

```APIDOC
## GET /api/search

### Description
Performs a unified search across playlists, tracks, artists, and downloads.

### Method
GET

### Endpoint
/api/search

### Parameters
#### Query Parameters
- **q** (string) - Required - Search query string

### Response
#### Success Response (200)
- **playlists** (array) - Matching playlists
- **tracks** (array) - Matching tracks
- **artists** (array) - Matching artists
- **downloads** (array) - Matching downloads

#### Response Example
{
  "playlists": [
    { "id": "...", "name": "Taylor Swift Essentials", "track_count": 50 }
  ],
  "tracks": [
    { "id": "...", "name": "Anti-Hero", "artist": "Taylor Swift", "playlist_name": "Top Hits" }
  ],
  "artists": [
    { "id": "...", "name": "Taylor Swift", "image_url": "..." }
  ],
  "downloads": [
    { "id": 123, "track_name": "Cruel Summer", "artist": "Taylor Swift", "status": "completed" }
  ]
}
```

--------------------------------

### GET /api/logs/recent

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Retrieves recent log entries from the in-memory ring buffer for instant access.

```APIDOC
## GET /api/logs/recent

### Description
Retrieves recent log entries from the in-memory ring buffer for instant access.

### Method
GET

### Endpoint
/api/logs/recent

### Parameters
#### Query Parameters
- **count** (integer) - Optional - Number of log entries to retrieve

### Response
#### Success Response (200)
- **logs** (array) - List of log objects

#### Response Example
[
  {
    "timestamp": "2024-01-15T10:30:00.000Z",
    "level": "info",
    "source": "downloader",
    "message": "Completed: Artist - Track Name",
    "meta": {"downloadId": 456, "fileSize": 28456789}
  }
]
```

--------------------------------

### GET /api/artists/{id}/releases

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Retrieves all discovered releases for a specific artist.

```APIDOC
## GET /api/artists/{id}/releases

### Description
Retrieves all discovered releases for a specific artist.

### Method
GET

### Endpoint
/api/artists/{id}/releases

### Parameters
#### Path Parameters
- **id** (string) - Required - Artist ID

### Response
#### Success Response (200)
- **id** (string) - Release ID
- **artist_id** (string) - Artist ID
- **album_name** (string) - Album name
- **album_type** (string) - Album type
- **release_date** (string) - Release date
- **is_downloaded** (integer) - Download status
- **discovered_at** (string) - Discovery timestamp

#### Response Example
[
  {
    "id": "rel123",
    "artist_id": "abc123",
    "album_name": "Short n' Sweet",
    "album_type": "album",
    "release_date": "2024-08-23",
    "is_downloaded": 1,
    "discovered_at": "2024-08-23T00:05:00.000Z"
  }
]
```

--------------------------------

### GET /api/webhooks/{id}/deliveries

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Retrieves delivery attempts for a specific webhook.

```APIDOC
## GET /api/webhooks/{id}/deliveries

### Description
Retrieves delivery attempts for a specific webhook with status and response codes.

### Method
GET

### Endpoint
/api/webhooks/{id}/deliveries

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the webhook

#### Query Parameters
- **limit** (integer) - Optional - Number of records to return
```

--------------------------------

### Get New Releases (Last 30 Days)

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Retrieve new releases from all monitored artists within a specified period, such as the last 30 days. Use the `days` query parameter to adjust the time frame.

```bash
curl -X GET "http://localhost:3001/api/artists/releases/new?days=30" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Get Webhook Delivery History

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Retrieves a list of delivery attempts for a specific webhook.

```bash
curl -X GET "http://localhost:3001/api/webhooks/uuid-here/deliveries?limit=50" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### GET /api/playlists

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Retrieves a list of all imported playlists, including metadata such as track count, owner, and tracking status.

```APIDOC
## GET /api/playlists

### Description
Retrieves all imported playlists ordered by creation date, including metadata like track count, owner, and tracking status.

### Method
GET

### Endpoint
/api/playlists

### Response
#### Success Response (200)
- **Array** (object) - List of playlist objects

#### Response Example
[
  {
    "id": "37i9dQZF1DXcBWIGoYBM5M",
    "name": "Today's Top Hits",
    "owner": "Spotify",
    "image_url": "https://i.scdn.co/image/...",
    "spotify_url": "https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M",
    "track_count": 50,
    "is_tracked": 1,
    "poll_interval": 300,
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T12:00:00.000Z"
  }
]
```

--------------------------------

### Cancel a Queued Download

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Cancel a download that is currently in the queue and has not yet started processing. This prevents the download from proceeding.

```bash
curl -X POST "http://localhost:3001/api/downloads/458/cancel" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### GET /api/artists/digest

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Returns a digest of all releases discovered in the past week, useful for generating weekly summaries.

```APIDOC
## GET /api/artists/digest

### Description
Returns a digest of all releases discovered in the past week, useful for generating weekly summaries.

### Method
GET

### Endpoint
/api/artists/digest

### Response
#### Success Response (200)
- **period_start** (string) - The start date of the digest period.
- **period_end** (string) - The end date of the digest period.
- **total** (integer) - The total number of releases in the digest.
- **releases** (array) - A list of discovered releases.
  - **id** (string) - The unique identifier for the release.
  - **album_name** (string) - The name of the album.
  - **artist_name** (string) - The name of the artist.
  - **release_date** (string) - The release date of the album.
  - **discovered_at** (string) - The timestamp when the release was discovered.

#### Response Example
```json
{
  "period_start": "2024-01-08",
  "period_end": "2024-01-15",
  "total": 8,
  "releases": [
    {
      "id": "rel123",
      "album_name": "New Album",
      "artist_name": "Artist Name",
      "release_date": "2024-01-12",
      "discovered_at": "2024-01-12T00:05:00.000Z"
    }
  ]
}
```
```

--------------------------------

### Get Storage Statistics

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Fetches historical storage usage data, providing the most recent snapshot for current state. A limit can be specified for historical data.

```bash
curl -X GET "http://localhost:3001/api/analytics/storage?limit=168" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Get Artist Releases

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Retrieve all discovered releases for a particular artist, identified by their ID. The response includes details like album name, type, release date, and download status.

```bash
curl -X GET "http://localhost:3001/api/artists/abc123/releases" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Get Recent Logs

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Retrieves recent log entries from the in-memory ring buffer. Use the 'count' parameter to specify the number of logs.

```bash
curl -X GET "http://localhost:3001/api/logs/recent?count=100" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### GET /api/playlists/:id

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Retrieves detailed information for a specific playlist, including all tracks, their download status, and duplicate detection information.

```APIDOC
## GET /api/playlists/:id

### Description
Retrieves detailed playlist information including all tracks with their download status and duplicate detection across other playlists.

### Method
GET

### Endpoint
/api/playlists/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The Spotify playlist ID

### Response
#### Success Response (200)
- **playlist** (object) - Detailed playlist object including tracks array

#### Response Example
{
  "id": "37i9dQZF1DXcBWIGoYBM5M",
  "name": "Today's Top Hits",
  "owner": "Spotify",
  "track_count": 50,
  "tracks": [
    {
      "id": "4PTG3Z6ehGkBFwjybzWkR8",
      "position": 1,
      "name": "Espresso",
      "artist": "Sabrina Carpenter",
      "album": "Espresso",
      "duration_ms": 175459,
      "isrc": "USUM72404062",
      "download": {
        "id": 123,
        "status": "completed",
        "file_path": "/downloads/Sabrina Carpenter/Espresso/01 - Espresso.flac",
        "file_size": 28456789,
        "quality_verified": 1
      },
      "also_in": ["Summer Vibes 2024", "Pop Hits"]
    }
  ]
}
```

--------------------------------

### Get Download Queue Status

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Retrieve the current status of the download queue, including the number of queued, active, and the maximum concurrent downloads allowed.

```bash
curl -X GET "http://localhost:3001/api/downloads/queue" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Configure SpotitoFLAC environment variables

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Define application settings such as download paths, authentication tokens, and server ports in the .env file.

```bash
# .env configuration file

# Path to dab-downloader binary (leave empty to use PATH)
DAB_DOWNLOADER_PATH=

# Directory where downloaded files are stored
DOWNLOAD_DIR=./downloads

# New releases folder (inside DOWNLOAD_DIR)
NEW_RELEASES_DIR=New Releases

# Access token for web UI authentication
ACCESS_TOKEN=your_secure_token_here

# Server port
PORT=3001

# CORS origin for frontend
CORS_ORIGIN=http://localhost:5173

# Log level: debug | info | warn | error
LOG_LEVEL=info

# Playlist polling interval in seconds (default: 300 = 5 minutes)
DEFAULT_POLL_INTERVAL=300

# Max concurrent downloads
MAX_CONCURRENT_DOWNLOADS=3

# File naming template
# Variables: {artist}, {album}, {title}, {track_number}, {disc_number},
#            {year}, {genre}, {isrc}, {playlist_name}, {position}, {format}
FILE_NAMING_TEMPLATE={artist}/{album}/{position} - {title}.{format}

# Quality upgrade check interval in hours (default: 168 = weekly)
QUALITY_CHECK_INTERVAL=168
```

--------------------------------

### Import Playlists

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Imports one or more Spotify playlists by URL to begin tracking and downloading.

```bash
# Import single playlist
curl -X POST "http://localhost:3001/api/playlists" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M"}'

# Import multiple playlists
curl -X POST "http://localhost:3001/api/playlists" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M",
      "https://open.spotify.com/playlist/37i9dQZF1DX0XUsuxWHRQd"
    ]
  }'

# Response
{
  "results": [
    { "id": "37i9dQZF1DXcBWIGoYBM5M", "name": "Today's Top Hits", "track_count": 50, "status": "ok" },
    { "id": "37i9dQZF1DX0XUsuxWHRQd", "name": "RapCaviar", "track_count": 50, "status": "ok" }
  ]
}
```

--------------------------------

### Preview Naming Template

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Validates a naming template string and returns a preview of the resulting filename.

```bash
curl -X POST "http://localhost:3001/api/settings/preview-template" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template": "{playlist_name}/{artist} - {title}.{format}"}'
```

--------------------------------

### List Webhooks

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Retrieves all configured webhooks, including their event types, status, and retry configurations.

```bash
curl -X GET "http://localhost:3001/api/webhooks" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### List Downloads

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Retrieves a paginated list of download records.

```bash
# Get all downloads
curl -X GET "http://localhost:3001/api/downloads?limit=50&offset=0" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Create Webhook

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Registers a new webhook for Discord, Slack, or generic integrations. Requires a valid bearer token for authorization.

```bash
curl -X POST "http://localhost:3001/api/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Discord Notifications",
    "url": "https://discord.com/api/webhooks/123456/abcdef",
    "type": "discord",
    "events": ["download_complete", "download_failed", "new_release_found"],
    "retry_count": 3,
    "retry_delay": 5
  }'
```

```bash
curl -X POST "http://localhost:3001/api/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Slack Channel",
    "url": "https://hooks.slack.com/services/T00/B00/XXXX",
    "type": "slack",
    "events": ["download_complete", "weekly_digest"]
  }'
```

```bash
curl -X POST "http://localhost:3001/api/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom Integration",
    "url": "https://api.example.com/webhook",
    "type": "generic",
    "events": ["download_complete", "new_release_found"],
    "secret": "your-hmac-secret-key",
    "headers": {"X-Custom-Header": "value"}
  }'
```

--------------------------------

### WebSocket Client Connection

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Establishes a WebSocket connection for real-time events. Authentication is handled via a query parameter. Handles various event types like download progress, completion, and errors.

```javascript
// Client-side WebSocket connection
const token = localStorage.getItem('spotitoflac_token');
const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
const ws = new WebSocket(`${protocol}//${window.location.host}/ws?token=${encodeURIComponent(token)}`);

ws.onopen = () => console.log('Connected to SpotitoFLAC');

ws.onmessage = (event) => {
  const { type, data, timestamp } = JSON.parse(event.data);

  switch (type) {
    case 'download_progress':
      // { downloadId, trackId, status, percent, trackName, artist }
      console.log(`${data.artist} - ${data.trackName}: ${data.percent}%`);
      break;
    case 'download_complete':
      // { downloadId, trackId, trackName, artist, filePath, fileSize, verified }
      console.log(`Completed: ${data.filePath} (${data.fileSize} bytes)`);
      break;
    case 'download_failed':
      // { downloadId, trackId, trackName, artist, error }
      console.error(`Failed: ${data.error}`);
      break;
    case 'new_tracks':
      // Emitted when playlist poll detects new tracks
      console.log('New tracks detected:', data);
      break;
    case 'new_release_found':
      // { artistName, albumName, releaseDate }
      console.log(`New release: ${data.artistName} - ${data.albumName}`);
      break;
    case 'log_entry':
      // Real-time log streaming
      console.log(`[${data.level}] ${data.message}`);
      break;
  }
};

ws.onclose = () => {
  // Auto-reconnect after 3 seconds
  setTimeout(() => connectWebSocket(), 3000);
};
```

--------------------------------

### POST /api/settings/preview-template

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Tests a naming template without saving it.

```APIDOC
## POST /api/settings/preview-template

### Description
Tests a naming template without saving it, showing how files would be named.

### Method
POST

### Endpoint
/api/settings/preview-template

### Request Body
- **template** (string) - Required - The naming template to preview
```

--------------------------------

### Create Webhook

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Creates a new webhook endpoint. Supports Discord, Slack, ntfy, and generic JSON formats.

--------------------------------

### Global Search

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Performs a unified search across playlists, tracks, artists, and downloads. Use the 'q' parameter for the search query.

```bash
curl -X GET "http://localhost:3001/api/search?q=taylor" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### List All Playlists

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Retrieves a list of all imported playlists with their metadata and tracking status.

```bash
# Get all playlists
curl -X GET "http://localhost:3001/api/playlists" \
  -H "Authorization: Bearer $TOKEN"

# Response
[
  {
    "id": "37i9dQZF1DXcBWIGoYBM5M",
    "name": "Today's Top Hits",
    "owner": "Spotify",
    "image_url": "https://i.scdn.co/image/...",
    "spotify_url": "https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M",
    "track_count": 50,
    "is_tracked": 1,
    "poll_interval": 300,
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T12:00:00.000Z"
  }
]
```

--------------------------------

### Retry All Failed Downloads

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Initiate a bulk operation to retry all downloads that are currently in a failed state. This is useful for re-attempting multiple failed downloads at once.

```bash
curl -X POST "http://localhost:3001/api/downloads/retry-all" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### POST /api/downloads

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Queues selected tracks for download with optional format and bitrate settings.

```APIDOC
## POST /api/downloads

### Description
Queues selected tracks for download with optional format and bitrate settings.

### Method
POST

### Endpoint
/api/downloads

### Parameters
#### Request Body
- **trackIds** (array) - Required - List of Spotify track IDs
- **playlistId** (string) - Optional - Spotify playlist ID
- **format** (string) - Optional - Download format (e.g., flac)

### Response
#### Success Response (200)
- **results** (array) - Status of each queued track
- **queue** (object) - Updated queue state

#### Response Example
{
  "results": [
    { "trackId": "4PTG3Z6ehGkBFwjybzWkR8", "status": "queued", "downloadId": 457 },
    { "trackId": "7qiZfU4dY1lWllzX7mPBI3", "status": "queued", "downloadId": 458 }
  ],
  "queue": { "queued": 7, "active": 2, "maxConcurrent": 3 }
}
```

--------------------------------

### Update Settings

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Updates application settings. Only recognized keys are persisted.

```bash
curl -X PUT "http://localhost:3001/api/settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "default_format": "flac",
    "max_concurrent": "5",
    "naming_template": "{artist}/{album}/{track_number} - {title}.{format}",
    "poll_interval": "600"
  }'
```

--------------------------------

### List Monitored Artists

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Fetch a list of all artists currently being monitored for new releases. The response includes release statistics and the next check time.

```bash
curl -X GET "http://localhost:3001/api/artists" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Test Webhook

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Triggers a test notification to verify the webhook configuration.

```bash
curl -X POST "http://localhost:3001/api/webhooks/uuid-here/test" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### POST /api/webhooks

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Creates a new webhook for Discord, Slack, or generic integrations.

```APIDOC
## POST /api/webhooks

### Description
Creates a new webhook configuration for notifications.

### Method
POST

### Endpoint
/api/webhooks

### Request Body
- **name** (string) - Required - Name of the webhook
- **url** (string) - Required - Webhook destination URL
- **type** (string) - Required - Type of webhook (discord, slack, generic)
- **events** (array) - Required - List of events to trigger the webhook
- **retry_count** (integer) - Optional - Number of retries
- **retry_delay** (integer) - Optional - Delay between retries
- **secret** (string) - Optional - HMAC secret key for generic webhooks
- **headers** (object) - Optional - Custom headers for generic webhooks

### Response
#### Success Response (200)
- **id** (string) - Webhook ID
- **name** (string) - Webhook name
- **url** (string) - Webhook URL
- **type** (string) - Webhook type
- **events** (string) - JSON string of events
- **enabled** (integer) - Enabled status
- **created_at** (string) - Creation timestamp
```

--------------------------------

### POST /api/downloads/retry-all

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Bulk operation to retry all downloads with failed status.

```APIDOC
## POST /api/downloads/retry-all

### Description
Bulk operation to retry all downloads with failed status.

### Method
POST

### Endpoint
/api/downloads/retry-all

### Response
#### Success Response (200)
- **results** (array) - List of retried download IDs and statuses
- **queue** (object) - Updated queue state

#### Response Example
{
  "results": [
    { "id": 456, "status": "queued" },
    { "id": 461, "status": "queued" }
  ],
  "queue": { "queued": 9, "active": 2, "maxConcurrent": 3 }
}
```

--------------------------------

### POST /api/playlists

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Imports one or more Spotify playlists by URL, triggering track extraction and artist monitoring registration.

```APIDOC
## POST /api/playlists

### Description
Imports one or more Spotify playlist URLs. Automatically extracts all tracks and registers artists for release monitoring.

### Method
POST

### Endpoint
/api/playlists

### Parameters
#### Request Body
- **url** (string) - Optional - Single playlist URL
- **urls** (array) - Optional - List of playlist URLs

### Response
#### Success Response (200)
- **results** (array) - List of import status objects

#### Response Example
{
  "results": [
    { "id": "37i9dQZF1DXcBWIGoYBM5M", "name": "Today's Top Hits", "track_count": 50, "status": "ok" },
    { "id": "37i9dQZF1DX0XUsuxWHRQd", "name": "RapCaviar", "track_count": 50, "status": "ok" }
  ]
}
```

--------------------------------

### PUT /api/settings

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Updates application settings.

```APIDOC
## PUT /api/settings

### Description
Updates application settings. Only recognized setting keys are persisted.

### Method
PUT

### Endpoint
/api/settings

### Request Body
- **default_format** (string) - Optional
- **max_concurrent** (string) - Optional
- **naming_template** (string) - Optional
- **poll_interval** (string) - Optional
```

--------------------------------

### Subscribe to WebSocket events in React

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Use the useWebSocket hook to listen for download progress and completion events. Ensure cleanup functions are returned to prevent memory leaks on component unmount.

```javascript
import { useWebSocket } from './hooks/useWebSocket';
import { useEffect } from 'react';

function DownloadProgress() {
  const { connected, on } = useWebSocket();

  useEffect(() => {
    // Subscribe to download progress events
    const unsubProgress = on('download_progress', (data) => {
      console.log(`Download ${data.downloadId}: ${data.percent}%`);
    });

    // Subscribe to completion events
    const unsubComplete = on('download_complete', (data) => {
      console.log(`Finished: ${data.trackName}`);
    });

    // Cleanup subscriptions on unmount
    return () => {
      unsubProgress();
      unsubComplete();
    };
  }, [on]);

  return (
    <div>
      <span>WebSocket: {connected ? 'Connected' : 'Disconnected'}</span>
    </div>
  );
}
```

--------------------------------

### Add Artist to Monitor

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Add a new artist to the system for release monitoring. This can be done manually or is often automated when importing playlists.

```bash
curl -X POST "http://localhost:3001/api/artists" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Taylor Swift",
    "spotify_url": "https://open.spotify.com/artist/06HL4z0CvFAxyc27GXpf02",
    "image_url": "https://i.scdn.co/image/..."
  }'
```

--------------------------------

### Filter Downloads by Status

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Use this endpoint to retrieve downloads filtered by their status (e.g., completed, queued, downloading, failed). Specify the status and an optional limit for the number of results.

```bash
curl -X GET "http://localhost:3001/api/downloads?status=completed&limit=100" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Filter Downloads by Playlist

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Retrieve downloads associated with a specific playlist by providing the playlist ID. An authorization token is required.

```bash
curl -X GET "http://localhost:3001/api/downloads?playlist_id=37i9dQZF1DXcBWIGoYBM5M" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### POST /api/artists

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Adds a new artist to the release monitoring system.

```APIDOC
## POST /api/artists

### Description
Adds a new artist to the release monitoring system.

### Method
POST

### Endpoint
/api/artists

### Parameters
#### Request Body
- **name** (string) - Required - Artist name
- **spotify_url** (string) - Required - Spotify URL
- **image_url** (string) - Optional - Image URL

### Response
#### Success Response (200)
- **id** (string) - Artist ID
- **name** (string) - Artist name
- **spotify_url** (string) - Spotify URL
- **created_at** (string) - Creation timestamp

#### Response Example
{
  "id": "def456",
  "name": "Taylor Swift",
  "spotify_url": "https://open.spotify.com/artist/06HL4z0CvFAxyc27GXpf02",
  "created_at": "2024-01-15T10:30:00.000Z"
}
```

--------------------------------

### POST /api/downloads/{id}/retry

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Re-queues a failed download for another attempt.

```APIDOC
## POST /api/downloads/{id}/retry

### Description
Re-queues a failed download for another attempt, incrementing the retry counter.

### Method
POST

### Endpoint
/api/downloads/{id}/retry

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the failed download

### Response
#### Success Response (200)
- **id** (integer) - New download ID
- **status** (string) - Status of the download

#### Response Example
{ "id": 459, "status": "queued" }
```

--------------------------------

### POST /api/webhooks/{id}/test

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Sends a test notification to verify webhook configuration.

```APIDOC
## POST /api/webhooks/{id}/test

### Description
Sends a test notification to verify webhook configuration.

### Method
POST

### Endpoint
/api/webhooks/{id}/test

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the webhook
```

--------------------------------

### Toggle Playlist Tracking

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Updates the tracking status and polling interval for a specific playlist.

```bash
# Enable tracking with custom poll interval (600 seconds)
curl -X PUT "http://localhost:3001/api/playlists/37i9dQZF1DXcBWIGoYBM5M/track" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "poll_interval": 600}'

# Response
{
  "is_tracked": true,
  "poll_interval": 600
}
```

--------------------------------

### Retry a Failed Download

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Re-queue a specific download that previously failed. This action increments the retry counter for the download.

```bash
curl -X POST "http://localhost:3001/api/downloads/456/retry" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### PUT /api/webhooks/{id}

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Updates an existing webhook configuration.

```APIDOC
## PUT /api/webhooks/{id}

### Description
Updates an existing webhook configuration.

### Method
PUT

### Endpoint
/api/webhooks/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the webhook

### Request Body
- **enabled** (boolean) - Optional - Enable or disable the webhook
- **events** (array) - Optional - List of events to trigger the webhook
```

--------------------------------

### Update Webhook

Source: https://context7.com/crashed6767/spotitoflac/llms.txt

Modifies an existing webhook configuration by its UUID.

```bash
curl -X PUT "http://localhost:3001/api/webhooks/uuid-here" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false,
    "events": ["download_complete", "system_error"]
  }'
```