API Reference

Supernova API Reference

Supernova's native API is served under /api/ (distinct from the Subsonic API served under /rest/). The native API provides advanced functionality like plugin management, raw streaming, and batch downloads.

Authentication

All endpoints (except login) require a valid JWT token passed in the Authorization header: Authorization: Bearer <your_sn_token>

Key Endpoints

1. Library Management

• GET /api/library/artists
  • Returns a paginated list of all artists in the library.
• GET /api/library/albums?artist_id=<id>
  • Returns albums, optionally filtered by artist.
• GET /api/library/tracks?album_id=<id>
  • Returns tracks for a specific album.

2. Playback & Media

• GET /api/stream/track/:id
  • Streams the raw audio file. Supports HTTP range requests for seeking.
• GET /api/art/album/:id
  • Returns the album cover art image.
• GET /api/download/track/:id
  • Forces a download of the track file with proper Content-Disposition.
• GET /api/download/album/:id
  • On-the-fly streaming zip of all tracks in the specified album.

3. Plugin Management

• GET /api/plugins
  • Returns the status of all registered background plugins.
• POST /api/plugins/:id/run
  • Dispatches a background job for the specified plugin (e.g., autotagger, deduper).

4. Podcasts

• GET /api/plugins/podcasts/search?q=<query>
  • Searches the PodcastIndex network.
• GET /api/plugins/podcasts/episodes?id=<feed_id>
  • Fetches episodes for a specific podcast feed.