Home Top

đŸŽĩ dizzoBX API

Complete REST API Documentation

Base URL: http://localhost:3000

📑 Table of Contents

đŸŽĩ Songs Endpoints

GET /api/songs

Get all songs with optional filters and sorting

Query Parameters:
search string optional
Search by artist, title, or album name
genre string optional
Filter by genre
style string optional
Filter by music style
mood string optional
Filter by mood
sortBy string optional
Sort results: 'artist', 'title', 'album', or 'year'
Example Requests:
GET /api/songs
GET /api/songs?search=drake
GET /api/songs?genre=Hip-Hop&sortBy=year
GET /api/songs?mood=energetic&style=Electronic
Response Example:
[
  {
    "id": 1,
    "title": "Song Title",
    "artist": "Artist Name",
    "album": "Album Name",
    "genre": "Hip-Hop",
    "style": "Trap",
    "mood": "energetic",
    "year": 2024,
    "track": "1/12",
    "img": "https://...",
    "path": "https://...",
    "avatar": "https://...",
    "fanart": "https://..."
  }
]
GET /api/songs/:id

Get a single song by ID

URL Parameters:
id number required
Song ID
Example Request:
GET /api/songs/123
Response Example:
{
  "id": 123,
  "title": "Song Title",
  "artist": "Artist Name",
  "album": "Album Name",
  "genre": "Hip-Hop",
  "style": "Trap",
  "mood": "energetic",
  "year": 2024,
  "path": "https://...",
  "img": "https://..."
}

🎤 Artists Endpoints

GET /api/artists

Get all unique artists in alphabetical order

Example Request:
GET /api/artists
Response Example:
[
  "Adele",
  "Drake",
  "Ed Sheeran",
  "Taylor Swift",
  ...
]
GET /api/artists/:artist/meta

Get artist metadata including bio and thumbnail

URL Parameters:
artist string required
Artist name (URL encoded)
Example Request:
GET /api/artists/Drake/meta
Response Example:
{
  "artist": "Drake",
  "thumb": "/assets/thumb/drake.jpg",
  "bio": "Canadian rapper and singer..."
}
GET /api/artists/:artist/albums

Get all albums by a specific artist

URL Parameters:
artist string required
Artist name (URL encoded)
Example Request:
GET /api/artists/Drake/albums
Response Example:
[
  {
    "name": "Album Name",
    "artist": "Drake",
    "year": 2023,
    "cover": "https://...",
    "songs": [...]
  }
]

đŸ’ŋ Albums Endpoints

GET /api/albums/:artist/:album

Get all tracks from a specific album

URL Parameters:
artist string required
Artist name (URL encoded)
album string required
Album name (URL encoded)
Example Request:
GET /api/albums/Drake/Certified%20Lover%20Boy
Response Example:
[
  {
    "id": 1,
    "title": "Track 1",
    "artist": "Drake",
    "album": "Certified Lover Boy",
    "year": 2021,
    "track": "1/21",
    ...
  },
  ...
]

🎛ī¸ Filters & Metadata

GET /api/filters

Get all available genres, styles, and moods for filtering

Example Request:
GET /api/filters
Response Example:
{
  "genres": [
    "Hip-Hop",
    "Pop",
    "Rock",
    "Electronic",
    ...
  ],
  "styles": [
    "Trap",
    "House",
    "Alternative",
    ...
  ],
  "moods": [
    "energetic",
    "chill",
    "melancholic",
    ...
  ]
}

🌐 External API Proxies

📌 Note:
These endpoints proxy external music services to avoid CORS issues when fetching chart data.

iTunes Top Charts

GET /api/itunes/:type

Get iTunes top songs (all genres)

Example Request:
GET /api/itunes/topsongs
GET /api/itunes/:type/:genre

Get iTunes top songs by genre

URL Parameters:
genre string required
Options: pop, hiphop, rock, country, dance, rnb
Example Request:
GET /api/itunes/topsongs/hiphop

Deezer Charts

GET /api/deezer/:type

Get Deezer global chart

Example Request:
GET /api/deezer/chart
GET /api/deezer/:type/:genre

Get Deezer chart by genre

URL Parameters:
genre string required
Options: pop, hiphop, rock, dance, rnb
Example Request:
GET /api/deezer/chart/dance

🗂ī¸ File Management & Admin Endpoints

GET /api/files/audio

List audio files available on the server (filename, size, mtime).

Example Request:
GET /api/files/audio
GET /api/files/thumbs

List thumbnail images in /assets/thumb.

Example Request:
GET /api/files/thumbs
GET /assets/thumb/:filename/small

Serve a small, prefixed thumbnail variant. The server prefers a prefixed small file /assets/thumb/small/th_{filename} and will generate it on-demand from the original when sharp is available. If missing, the original thumbnail is returned as a fallback.

Usage Notes
Client UI should prefer the small accessor (e.g. append /small to stored img values) so the UI requests lightweight images without changing persisted metadata. The server stores original thumbs as /assets/thumb/{name} and keeps prefixed smalls under /assets/thumb/small/th_{name}.
GET /assets/thumb/suaimforme0000.jpeg/small
POST /api/upload

Upload audio files (multipart/form-data). Adds entries to the local tags store when possible.

Form Fields:
files file[] required
One or more audio files
curl -F "files=@track.mp3" http://localhost:3000/api/upload
GET /api/logs/recent-adds

Retrieve recent uploads log. Returns an array of recent add objects (ts, meta, ip, region).

GET /api/logs/recent-adds
POST /api/logs/recent-adds/clear

Clear the recent-adds log and create a timestamped backup in /assets/logs/backup/.

POST /api/logs/recent-adds/clear
GET /api/logs/config

Get logs configuration (currently: maxEntries).

GET /api/logs/config
POST /api/logs/config

Set logs configuration. JSON body: { "maxEntries": 500 }. Max allowed value is 10000.

curl -H "Content-Type: application/json" -d '{"maxEntries":500}' http://localhost:3000/api/logs/config
DELETE /api/files/audio/:filename

Delete (move to backup) an audio file and remove its tag entry. Filename should be URL encoded.

DELETE /api/files/audio/112%20-%20112%20Intro.mp3
DELETE /api/files/thumbs/:filename

Delete or backup a thumbnail image and clear references in the local tags store.

PATCH /api/tags/:id

Update metadata for a song in tags-local.json (title, artist, album, img, path, etc.).

PATCH /api/tags/123 -d '{"title":"New Title"}'
POST /api/tags/:id/thumb

Upload a replacement thumbnail for a song. Server saves image, updates tag, and attempts to embed into MP3 ID3 when possible.

Form Fields:
thumb file required
GET /proxy/audio?url=<url>

Proxy or serve audio. If url points to a local /assets/ path the server serves it with Range support; remote http(s) URLs are proxied.

GET /proxy/audio?url=/assets/audio/track.mp3
POST /admin/reload-tags

Reload tags-local.json into server memory (admin use).

POST /admin/clear-analytics

Clear the play tracking log (plays.ndjson).

📡 Play Tracking (NDJSON)

ℹī¸ Overview:
Plays are recorded server-side to a newline-delimited JSON file (`plays.ndjson`) for lightweight analytics without a database. By default this endpoint does not require user login; you can enable simple token-based protection by setting the `TRACKING_TOKEN` environment variable on the server.
POST /track_play

Record a play event. Appends one JSON object per line to `plays.ndjson`.

Body (JSON):
id number required
Song ID
title string optional
Song title (helpful for readable logs)
artist string optional
Artist name
album string optional
Album name
Headers:
X-Tracking-Token string optional
If `TRACKING_TOKEN` is set on the server, provide this header to authenticate.
cURL Example:
curl -X POST http://localhost:3000/track_play \
  -H "Content-Type: application/json" \
  -d '{"id":123,"title":"Song Title","artist":"Artist"}'
Response Example:
{"ok":true}
GET /api/plays

Get recent plays and simple aggregates (by song, region). Returns last 100 plays and counts.

GET /api/plays/count

Get the total number of play entries recorded. Optional query: ?days=7 to count plays within the last N days.

GET /api/plays/count GET /api/plays/count?days=30
GET /api/analytics/recent

Get recent play events enriched with song metadata. Query: limit (default 100).

GET /api/analytics/recent?limit=50
GET /api/analytics/top

Get top-played tracks. Query: limit (default 20), days or since (timestamp ms) to limit timeframe.

GET /api/analytics/top?limit=20&days=7
Privacy & Storage
Entries include a server-side timestamp, a masked client IP (for approximate region only), and the user-agent string. The server masks IPs before writing to `plays.ndjson`.

📋 Song Object Schema

{
  "id": "number - Unique song identifier",
  "title": "string - Song title",
  "artist": "string - Artist name",
  "album": "string - Album name",
  "genre": "string - Music genre",
  "style": "string - Music style/subgenre",
  "mood": "string - Song mood/vibe",
  "year": "number - Release year",
  "track": "string - Track number (e.g., '1/12')",
  "img": "string - Album cover image URL",
  "path": "string - Audio file URL",
  "alternate": "string - Alternate version info",
  "born": "string|null - Artist birth info",
  "logo": "string - Artist logo URL",
  "avatar": "string - Artist avatar URL",
  "wide": "string|null - Wide banner image",
  "banner": "string - Banner image URL",
  "clearart": "string|null - Clear art image",
  "cutout": "string|null - Cutout image",
  "fanart": "string - Fan art/background image"
}

💡 Usage Tips

🔍 Search Tips:
  • Search is case-insensitive
  • Partial matches are supported (e.g., "dra" matches "Drake")
  • Search looks in artist, title, and album fields
đŸŽ¯ Filtering Tips:
  • Multiple filters can be combined
  • Use /api/filters to get available filter values
  • Filters are case-sensitive
📊 Sorting:
  • Year sorting is descending (newest first)
  • Text sorting (artist, title, album) is ascending (A-Z)
  • Only one sort parameter can be used at a time
🔗 URL Encoding:
  • Always URL encode artist and album names
  • Example: "Twenty One Pilots" → "Twenty%20One%20Pilots"
  • Special characters must be encoded

🧭 How to Use the API

Quick Start
Base URL: http://localhost:3000. Use simple HTTP clients like curl, fetch, or Postman to call the endpoints below.
GET /api/songs
List songs. Example: curl http://localhost:3000/api/songs
GET /proxy/audio?url=<url>
Stream or proxy audio. For local files use a path starting with /assets/. Example with Range header (seek support):
curl -H "Range: bytes=0-1023" "http://localhost:3000/proxy/audio?url=/assets/audio/track.mp3" --output - | head -c 1024
POST /api/upload
Upload audio files (multipart). Example:
curl -F "files=@/path/to/track.mp3" http://localhost:3000/api/upload
POST /track_play
Record a play event (NDJSON). Example:
curl -X POST http://localhost:3000/track_play \
  -H "Content-Type: application/json" \
  -d '{"id":123,"title":"Song Title","artist":"Artist"}'
Auth
If the server sets TRACKING_TOKEN, include header X-Tracking-Token: <token>.
POST /admin/reload-tags
Reload tags-local.json after editing or importing. Example:
curl -X POST http://localhost:3000/admin/reload-tags
Admin Token
If ADMIN_TOKEN is set, include header X-Admin-Token: <token>.
POST /admin/plays/delete
Delete one or more play entries from plays.ndjson by ts (timestamp) and/or id. Body: JSON with ts and/or id. Example:
curl -X POST http://localhost:3000/admin/plays/delete \
  -H "Content-Type: application/json" \
  -d '{"ts":1612345678901,"id":123}'
Admin Token
This endpoint requires the X-Admin-Token header when ADMIN_TOKEN is configured.
Browser fetch Example
Use /proxy/audio?url= for cross-origin remote audio or point directly to local paths (e.g. /assets/audio/track.mp3) when the file is hosted on the same server. 
fetch('/proxy/audio?url='+encodeURIComponent('/assets/audio/track.mp3'), { headers: { Range: 'bytes=0-1023' } })
  .then(r => r.arrayBuffer()).then(b => console.log('got', b.byteLength));

🗂ī¸ Meta / Admin Endpoints

GET /api/meta
List all artist metadata (reads public/assets/meta.json).
curl http://localhost:3000/api/meta
PUT /api/meta
Create or update a single artist meta entry. Send JSON body with fields like artist, thumb, avatar, etc.
curl -X PUT http://localhost:3000/api/meta \
  -H "Content-Type: application/json" \
  -d '{"artist":"My Artist","avatar":"/assets/meta/avatar/my_avatar.jpg"}'
POST /api/meta/upload
Upload an image for a meta field. Form fields: artist, field (e.g. avatar, thumb), and file (multipart).
curl -i -X POST \
  -F "artist=Automated Test Artist" \
  -F "field=avatar" \
  -F "file=@/path/to/avatar.jpg" \
  http://localhost:3000/api/meta/upload
On success the endpoint returns JSON with path (the new saved path). The server also persists the path into public/assets/meta.json and creates a backup.
GET /api/meta-bio
Serve extracted artist bios. Supports optional query ?id=<metaId> or ?artist=<name>. Without query returns the full bios object (may be large).
Query Parameters:
id string optional
Return a single bio entry by meta id.
artist string optional
Return a single bio entry matching artist name (case-insensitive).
Cache
Responses are cached (Cache-Control: max-age=86400) to allow efficient lazy-loading from the UI.
Filename Convention
Uploaded files are renamed by the server to a sanitized short-artist + field + timestamp pattern and saved under /assets/meta/<field>/. Example: ken_avatar020039443.jpg.
External Images
Some meta entries may reference external HTTP URLs. There is a maintenance script scripts/download-meta-images.js (one-time) that downloads external images into public/assets/meta/* and updates meta.json. Use it to localize remote art and improve reliability.
Querying by Artist
Fetch a single artist's metadata using a query parameter or a path parameter. Both match against the artist name (case-insensitive) and the alternate field when present. 
curl "http://localhost:3000/api/meta?q=James%20Blunt"
curl "http://localhost:3000/api/meta/artist/James%20Blunt"
Response (example):
{
  "artist": "James Blunt",
  "thumb": "/assets/meta/thumb/jam_thumb1769479514341721198.jpg",
  "website": "https://www.jamesblunt.com",
  "bio": "..."
}

📤 Shared Playlist Links

Create and access shareable playlist URLs for seamless music sharing

GET /api/shared-playlist-links

Retrieve all shared playlist links

curl http://localhost:3000/api/shared-playlist-links
Response:
{
  "shareId1": {
    "id": "1770159325304",
    "name": "My Favorite Songs",
    "songs": [...],
    "shareId": "shareId1",
    "sharedAt": "2026-02-03T12:00:00.000Z"
  },
  "shareId2": {
    ...
  }
}
POST /api/shared-playlist-links

Create a shareable playlist link

Request Body:
id string required
Playlist ID
name string required
Playlist name
songs array required
Array of song objects with id, title, artist, img, and path
shareId string required
Unique share identifier
sharedAt string optional
ISO timestamp when shared
curl -X POST http://localhost:3000/api/shared-playlist-links \
  -H "Content-Type: application/json" \
  -d '{
    "id": "1770159325304",
    "name": "My Favorite Songs",
    "songs": [
      {
        "id": 1700,
        "title": "No Longer Slaves",
        "artist": "Bethel Music",
        "img": "/assets/thumb/benolongerslav.jpeg/small",
        "path": "/assets/audio/Jonathan%20David%20%20-%20No%20Longer%20Slaves.mp3"
      }
    ],
    "shareId": "abc123def456",
    "sharedAt": "2026-02-03T12:00:00.000Z"
  }'
Response:
{
  "ok": true
}
GET /api/shared-playlist-links/:shareId

Retrieve a shared playlist by its share ID

Path Parameters:
shareId string required
The unique share identifier (14-character random string)
curl http://localhost:3000/api/shared-playlist-links/abc123def456
Response:
{
  "id": "1770159325304",
  "name": "My Favorite Songs",
  "songs": [
    {
      "id": 1700,
      "title": "No Longer Slaves",
      "artist": "Bethel Music",
      "img": "/assets/thumb/benolongerslav.jpeg/small",
      "path": "/assets/audio/Jonathan%20David%20%20-%20No%20Longer%20Slaves.mp3"
    }
  ],
  "shareId": "abc123def456",
  "sharedAt": "2026-02-03T12:00:00.000Z"
}

🔄 Usage Flow

  1. Create Playlist: User creates a playlist in the main app
  2. Generate Link: App calls POST /api/shared-playlist-links with playlist data
  3. Share URL: App generates URL like /shared-playlist.html?id=abc123def456
  4. Access Playlist: Recipients visit the URL, app calls GET /api/shared-playlist-links/:shareId
  5. Manage Playlists: Dashboard fetches all shared playlists via GET /api/shared-playlist-links
  6. Auto-Resolve: If songs lack paths, frontend fetches them from /api/songs/:id

đŸŽĩ Features

  • Auto-Play: Clicking next/prev immediately starts playback
  • Mobile Optimized: Responsive design with touch-friendly controls
  • iOS Compatible: SVG icons ensure consistent rendering
  • Path Resolution: Automatically resolves missing audio paths
  • Shareable URLs: Clean, short URLs for easy sharing
  • Admin Management: View and delete shared playlists from dashboard

🔗 Share Song to URL

POST /api/share-song

Create a shareable URL for a song

Request Body:
songId string/number required
The ID of the song to share
curl -X POST http://localhost:3000/api/share-song \
  -H "Content-Type: application/json" \
  -d '{"songId": 123}'
Response:
{
  "shareId": "abc123def456",
  "song": {
    "id": 123,
    "title": "Song Title",
    "artist": "Artist Name"
  }
}
GET /share/:shareId

Access the shared song player

Path Parameters:
shareId string required
The unique share ID
curl http://localhost:3000/share/abc123def456
Returns an HTML page with a mini player for the shared song