Skip to main content
API docs by Redocly

immerle extension API (1.0.0)

Download OpenAPI specification:Download

License: See repository

Native immerle REST API (first-run setup, capability discovery, activity feed, collaborative playlists and synchronized Jam sessions) that complements the Subsonic / OpenSubsonic API served under /rest/.

Served under /api/v1. Authenticated endpoints require a Bearer token in the Authorization header — a device JWT (obtained from POST /auth/sessions) or a personal API token. Setup, capability discovery and session creation are unauthenticated.

activity

Activity feed

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

admin

Sync genre/decade auto-playlists now

Admin only. Rebuilds every genre and decade auto-playlist from the local catalog immediately, returning how many synced successfully.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "synced": 0
}

Sync curated chart playlists now

Admin only. Fetches and upserts every curated chart playlist immediately, returning how many synced successfully.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "synced": 0
}

Get the cleanup sweep state

Admin only. Reports the eviction sweep state.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "intervalSeconds": 0,
  • "maxAgeSeconds": 0
}

Toggle the cleanup sweep

Admin only. Enables or disables the background eviction sweep at runtime (persisted; hot).

Authorizations:
BearerAuth
Request Body schema: application/json
required

Enable or disable the sweep

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "enabled": true,
  • "intervalSeconds": 0,
  • "maxAgeSeconds": 0
}

Run the cleanup sweep now

Admin only. Runs one eviction pass immediately and returns how many provider downloads were removed. Works even when the background sweep is disabled.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "removed": 0
}

Get the concert-discovery feature state

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "country": "FR",
  • "enabled": false,
  • "skiddleConfigured": false,
  • "ticketmasterConfigured": false
}

Update concert-discovery settings

Admin only. Partial update — only fields present are changed. API keys are write-only: the response never echoes them back.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Fields to change

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "country": "FR",
  • "enabled": false,
  • "skiddleConfigured": false,
  • "ticketmasterConfigured": false
}

Sync concert discovery now

Admin only. Searches every user's top-listened artists for upcoming shows near the configured country immediately, returning how many new matches were found.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "synced": 0
}

Unlink this instance from the hub

Admin only. Deletes this instance's data on the hub (best-effort) and clears the locally stored hub identity, returning the instance to the unlinked state. Returns the refreshed runtime settings.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "pendingRestart": [
    ],
  • "restartRequired": true,
  • "settings": {
    }
}

Get the live hub instance profile

Admin only. Fetches this instance's current name and sqid handle from the hub (the source of truth) and persists them, then returns the refreshed runtime settings. The HTTP exchange runs server-side.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "pendingRestart": [
    ],
  • "restartRequired": true,
  • "settings": {
    }
}

Update this instance on the hub

Admin only. Pushes the instance name and sqid (the editable, unique hub handle) to the hub, which validates sqid uniqueness, then persists the hub-canonical values. The HTTP exchange runs server-side. Returns the refreshed runtime settings.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Instance name and sqid

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "pendingRestart": [
    ],
  • "restartRequired": true,
  • "settings": {
    }
}

Discover instances on the hub

Admin only. Searches the hub for other instances by exact sqid or name (the hub excludes this instance and revoked ones). The HTTP exchange runs server-side.

Authorizations:
BearerAuth
query Parameters
q
required
string

Search query (sqid or name)

Responses

Response samples

Content type
application/json
{
  • "instances": [
    ]
}

Link with the hub

Admin only. Bootstraps the instance under the configured hub user id (federation.userId) and persists the hub-issued identity (instance UUID, sqid handle and private key). The full HTTP exchange runs server-side. Returns the refreshed runtime settings.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "pendingRestart": [
    ],
  • "restartRequired": true,
  • "settings": {
    }
}

List hub subscriptions

Admin only. Returns the instances this one follows on the hub. The HTTP exchange runs server-side.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "subscriptions": [
    ]
}

Subscribe to an instance

Admin only. Follows a target instance on the hub by instanceId (UUID) or sqid. The HTTP exchange runs server-side.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Target instance id or sqid

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "ok": true
}

Unsubscribe from an instance

Admin only. Stops following the instance with the given hub id (UUID). The HTTP exchange runs server-side.

Authorizations:
BearerAuth
path Parameters
id
required
string

Target instance id (UUID)

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Get the Hall of Fame feature state

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "enabled": true
}

Toggle the Hall of Fame feature

Authorizations:
BearerAuth
Request Body schema: application/json
required

Enable or disable

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "enabled": true
}

Get the Last.fm scrobbling feature state

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "configured": false,
  • "enabled": false
}

Update Last.fm scrobbling settings

Admin only. Partial update — only fields present are changed. The API key/secret are write-only: the response never echoes them back.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Fields to change

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "configured": false,
  • "enabled": false
}

Library scan state

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "scanning": true
}

Start a library scan

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "scanning": true
}

Stream server logs (SSE)

Admin only. Server-Sent Events stream of structured JSON log lines. Sends recent history immediately, then every new line as it's logged.

Authorizations:
BearerAuth

Responses

Get the offline-downloads feature state

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "enabled": true
}

Toggle the offline-downloads feature

Authorizations:
BearerAuth
Request Body schema: application/json
required

Enable or disable

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "enabled": true
}

Subscribe to a podcast feed

Authorizations:
BearerAuth
Request Body schema: application/json
required

Feed URL

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "description": "string",
  • "episodes": [
    ],
  • "error": "string",
  • "id": "string",
  • "imageUrl": "string",
  • "status": "string",
  • "title": "string",
  • "url": "string"
}

Delete a podcast episode

Authorizations:
BearerAuth
path Parameters
id
required
string

Episode id

Responses

List podcast directory providers

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "providers": [
    ]
}

Configure a podcast directory provider

Authorizations:
BearerAuth
path Parameters
name
required
string

Provider name

Request Body schema: application/json
required

Enabled + config

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "error": {
    }
}

Refresh all podcast feeds

Authorizations:
BearerAuth

Responses

Search podcast directories

Authorizations:
BearerAuth
query Parameters
q
required
string

Search terms

Responses

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Delete a podcast channel

Authorizations:
BearerAuth
path Parameters
id
required
string

Channel id

Responses

List on-demand providers

Admin only. Lists configured providers (built-in and dynamic) with their live status.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create or update an on-demand provider

Admin only. With only an endpoint (no name), creates an HTTP provider from its URL by probing /capabilities. With a name, updates it (HTTP config is validated against /capabilities).

Authorizations:
BearerAuth
Request Body schema: application/json
required

Provider config

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "active": true,
  • "builtin": true,
  • "capabilities": [
    ],
  • "config": "string",
  • "createdAt": "string",
  • "deletable": true,
  • "enabled": true,
  • "endpoint": "string",
  • "kind": "string",
  • "name": "string",
  • "sortOrder": 0,
  • "updatedAt": "string",
  • "version": 0
}

Reorder providers

Admin only. Sets the provider priority order (lower = higher priority). order lists every provider name, each exactly once. Order also decides which provider search falls back to when no explicit default is set.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Provider names in the desired order

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
[
  • {
    }
]

Delete a provider

Admin only. Removes a provider config and unregisters it.

Authorizations:
BearerAuth
path Parameters
name
required
string

Provider name

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Enable or disable a provider capability

Admin only. Switches one capability (trackSearch, artists, playlists, playlistSearch) of a provider on or off, applied to the live registry immediately. A disabled capability is never called: e.g. with trackSearch off, global search sends no request to that provider.

Authorizations:
BearerAuth
path Parameters
name
required
string

Provider name

capability
required
string

Capability key

Request Body schema: application/json
required

Enabled flag

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "active": true,
  • "builtin": true,
  • "capabilities": [
    ],
  • "config": "string",
  • "createdAt": "string",
  • "deletable": true,
  • "enabled": true,
  • "endpoint": "string",
  • "kind": "string",
  • "name": "string",
  • "sortOrder": 0,
  • "updatedAt": "string",
  • "version": 0
}

Enable or disable a provider

Admin only. Toggles a provider on or off; the change is applied to the live registry immediately.

Authorizations:
BearerAuth
path Parameters
name
required
string

Provider name

Request Body schema: application/json
required

Enabled flag

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "active": true,
  • "builtin": true,
  • "capabilities": [
    ],
  • "config": "string",
  • "createdAt": "string",
  • "deletable": true,
  • "enabled": true,
  • "endpoint": "string",
  • "kind": "string",
  • "name": "string",
  • "sortOrder": 0,
  • "updatedAt": "string",
  • "version": 0
}

List a provider's recent warn/error events

Admin only. Returns the most recent provider action failures (search/resolve/download), newest first.

Authorizations:
BearerAuth
path Parameters
name
required
string

Provider name

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get the radio feature state

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "enabled": true
}

Toggle the radio feature

Authorizations:
BearerAuth
Request Body schema: application/json
required

Enable or disable

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "enabled": true
}

Create a radio station

Authorizations:
BearerAuth
Request Body schema: application/json
required

Station

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "builtin": true,
  • "country": "string",
  • "coverUrl": "string",
  • "deletable": true,
  • "hasCover": true,
  • "homepageUrl": "string",
  • "id": "string",
  • "liked": true,
  • "name": "string",
  • "streamUrl": "string"
}

Delete a radio station

Authorizations:
BearerAuth
path Parameters
id
required
string

Station id

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Update a radio station

Authorizations:
BearerAuth
path Parameters
id
required
string

Station id

Request Body schema: application/json
required

Station

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "builtin": true,
  • "country": "string",
  • "coverUrl": "string",
  • "deletable": true,
  • "hasCover": true,
  • "homepageUrl": "string",
  • "id": "string",
  • "liked": true,
  • "name": "string",
  • "streamUrl": "string"
}

Get runtime settings

Admin only. Returns the current runtime settings (provider behaviour, artist avatars, scan cadence, federation) plus whether a restart is pending.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "pendingRestart": [
    ],
  • "restartRequired": true,
  • "settings": {
    }
}

Update runtime settings

Admin only. Partial update (send a JSON body with the fields to change; omitted fields keep their current value). Provider behaviour and the scan interval apply immediately (hot reload); avatars, the scan watcher and federation only take effect after a restart — the response sets restartRequired=true and lists the pending fields.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Settings fields to change (partial)

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "pendingRestart": [
    ],
  • "restartRequired": true,
  • "settings": {
    }
}

Get the smart-playlists feature state

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "enabled": true
}

Toggle the smart-playlists feature

Authorizations:
BearerAuth
Request Body schema: application/json
required

Enable or disable

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "enabled": true
}

Audio analysis status

Admin only. Whether local audio analysis can run (ffmpeg found) and is switched on (sonic.enabled setting), plus its progress over the local library.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "analyzed": 4210,
  • "available": true,
  • "enabled": true,
  • "failed": 3,
  • "total": 12000
}

Sonic duplicates

Admin only. Groups of analyzed tracks that sound identical and last about as long (within 3 s): the same recording under other tags, or in another format. Nothing is deleted; the admin picks which copy to keep. 404 when the sonic duplicates setting is off.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "groups": [
    ]
}

List library tracks

Admin only. Lists downloaded (local) tracks, newest first, with optional search and pagination.

Authorizations:
BearerAuth
query Parameters
query
string

Case-insensitive search over title/artist/album

limit
integer

Page size (default 50, max 200)

offset
integer

Offset for pagination

Responses

Response samples

Content type
application/json
{
  • "limit": 0,
  • "offset": 0,
  • "total": 0,
  • "tracks": [
    ]
}

Delete a track

Admin only. Removes the audio file and the track and all rows referencing it (annotations, shares, activity, downloads, playlist entries, scrobbles).

Authorizations:
BearerAuth
path Parameters
id
required
string

Track id

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Edit track metadata

Admin only. Edits a track's title, genre, year and track/disc number. Album and artist links are not changed.

Authorizations:
BearerAuth
path Parameters
id
required
string

Track id

Request Body schema: application/json
required

Fields to update (all optional)

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "album": "string",
  • "albumId": "string",
  • "artist": "string",
  • "artistId": "string",
  • "bitRate": 0,
  • "bpm": 0,
  • "comment": "string",
  • "composer": "string",
  • "contentType": "string",
  • "coverArt": "string",
  • "duration": 0,
  • "genre": "string",
  • "id": "string",
  • "lyrics": "string",
  • "movementName": "string",
  • "movementNumber": 0,
  • "participants": [
    ],
  • "playCount": 0,
  • "rating": 0,
  • "remote": true,
  • "replayGainAlbum": 0,
  • "replayGainTrack": 0,
  • "size": 0,
  • "starred": "string",
  • "suffix": "string",
  • "title": "string",
  • "titleSort": "string",
  • "track": 0,
  • "unresolved": true,
  • "work": "string",
  • "year": 0
}

Upload track cover

Admin only. Replaces a single track's cover art with an uploaded image (multipart form field "file").

Authorizations:
BearerAuth
path Parameters
id
required
string

Track id

Request Body schema:
required

Cover image (jpeg/png/gif/webp)

file (file)

Responses

Response samples

Content type
application/json
{
  • "album": "string",
  • "albumId": "string",
  • "artist": "string",
  • "artistId": "string",
  • "bitRate": 0,
  • "bpm": 0,
  • "comment": "string",
  • "composer": "string",
  • "contentType": "string",
  • "coverArt": "string",
  • "duration": 0,
  • "genre": "string",
  • "id": "string",
  • "lyrics": "string",
  • "movementName": "string",
  • "movementNumber": 0,
  • "participants": [
    ],
  • "playCount": 0,
  • "rating": 0,
  • "remote": true,
  • "replayGainAlbum": 0,
  • "replayGainTrack": 0,
  • "size": 0,
  • "starred": "string",
  • "suffix": "string",
  • "title": "string",
  • "titleSort": "string",
  • "track": 0,
  • "unresolved": true,
  • "work": "string",
  • "year": 0
}

List users

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "users": [
    ]
}

Create user

Authorizations:
BearerAuth
Request Body schema: application/json
required

User

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "admin": true,
  • "displayName": "string",
  • "email": "string",
  • "id": "string",
  • "scrobblingEnabled": true,
  • "username": "string"
}

Delete user

Authorizations:
BearerAuth
path Parameters
username
required
string

Username

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get user

Authorizations:
BearerAuth
path Parameters
username
required
string

Username

Responses

Response samples

Content type
application/json
{
  • "admin": true,
  • "displayName": "string",
  • "email": "string",
  • "id": "string",
  • "scrobblingEnabled": true,
  • "username": "string"
}

Update user

Authorizations:
BearerAuth
path Parameters
username
required
string

Username

Request Body schema: application/json
required

Changes

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get the Wrapped feature state

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "enabled": true
}

Toggle the Wrapped feature

Authorizations:
BearerAuth
Request Body schema: application/json
required

Enable or disable

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "enabled": true
}

catalog

List albums

Returns albums filtered/sorted by type (newest, recent, frequent, random, alphabeticalByName, byGenre, byYear, starred) with paging.

Authorizations:
BearerAuth
query Parameters
type
string
Default: "alphabeticalByName"

List type

size
integer
Default: 10

Page size

offset
integer

Offset

genre
string

Genre (for byGenre)

fromYear
integer

From year (for byYear)

toYear
integer

To year (for byYear)

Responses

Response samples

Content type
application/json
{
  • "albums": [
    ]
}

Get album

Returns an album with its merged (local + remote) tracklist.

Authorizations:
BearerAuth
path Parameters
id
required
string

Album id

Responses

Response samples

Content type
application/json
{
  • "artist": "string",
  • "artistId": "string",
  • "coverArt": "string",
  • "duration": 0,
  • "genre": "string",
  • "id": "string",
  • "name": "string",
  • "songCount": 0,
  • "starred": "string",
  • "tracks": [
    ],
  • "year": 0
}

List artists

Returns every artist in the catalog with the caller's per-artist starred state.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "artists": [
    ]
}

Get artist

Returns an artist with its (local + remote) albums. With ?songs=true each album's tracks are inlined.

Authorizations:
BearerAuth
path Parameters
id
required
string

Artist id

query Parameters
songs
boolean

Inline each album's tracks

Responses

Response samples

Content type
application/json
{
  • "albumCount": 0,
  • "albums": [
    ],
  • "coverArt": "string",
  • "id": "string",
  • "name": "string",
  • "starred": "string"
}

List genres

Returns every genre with its song and album counts.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "genres": [
    ]
}

List favorites

Returns the artists, albums and songs the caller has starred.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "albums": [
    ],
  • "artists": [
    ],
  • "songs": [
    ]
}

Search the catalog

Searches artists, albums, songs, public playlists and radio stations (merging remote-provider results when enabled, plus public Spotify playlists when the built-in spotify-playlist provider is enabled), returned as one list ranked by relevance to the query. type scopes the search server-side to just that result type.

Authorizations:
BearerAuth
query Parameters
q
required
string

Search query

type
string

Scope to one result type: artist, album, song, playlist or radio (default: all)

artistCount
integer
Default: 20

Max artists

albumCount
integer
Default: 20

Max albums

songCount
integer
Default: 20

Max songs

Responses

Response samples

Content type
application/json
{
  • "results": [
    ]
}

List songs by genre

Returns songs tagged with the given genre (paged).

Authorizations:
BearerAuth
query Parameters
genre
required
string

Genre name

count
integer
Default: 200

Page size

offset
integer

Offset

Responses

Response samples

Content type
application/json
{
  • "songs": [
    ]
}

Get song

Returns a single track by id.

Authorizations:
BearerAuth
path Parameters
id
required
string

Track id

Responses

Response samples

Content type
application/json
{
  • "album": "string",
  • "albumId": "string",
  • "artist": "string",
  • "artistId": "string",
  • "bitRate": 0,
  • "bpm": 0,
  • "comment": "string",
  • "composer": "string",
  • "contentType": "string",
  • "coverArt": "string",
  • "duration": 0,
  • "genre": "string",
  • "id": "string",
  • "lyrics": "string",
  • "movementName": "string",
  • "movementNumber": 0,
  • "participants": [
    ],
  • "playCount": 0,
  • "rating": 0,
  • "remote": true,
  • "replayGainAlbum": 0,
  • "replayGainTrack": 0,
  • "size": 0,
  • "starred": "string",
  • "suffix": "string",
  • "title": "string",
  • "titleSort": "string",
  • "track": 0,
  • "unresolved": true,
  • "work": "string",
  • "year": 0
}

Check whether a remote track has finished downloading

Read-only, never downloads. Poll this while playing a remote (not-yet-local) track to know when it's safe to seek.

Authorizations:
BearerAuth
path Parameters
id
required
string

Track id (remote or local)

Responses

Response samples

Content type
application/json
{
  • "local": true,
  • "song": {
    }
}

Get song lyrics

Returns a track's lyrics. When the stored tags carry [mm:ss.xx] timestamps the document is "synced" and every line has a startMs (ms).

Authorizations:
BearerAuth
path Parameters
id
required
string

Track id

Responses

Response samples

Content type
application/json
{
  • "lines": [
    ],
  • "synced": true
}

ratings

Clear an item's rating

Authorizations:
BearerAuth
path Parameters
id
required
string

Item id (song, album or artist)

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Rate an item

Sets the caller's rating (0–5) on the item. The item type is detected from the id.

Authorizations:
BearerAuth
path Parameters
id
required
string

Item id (song, album or artist)

Request Body schema: application/json
required

Rating

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "error": {
    }
}

Clear an item's rating

Authorizations:
BearerAuth
path Parameters
id
required
string

Item id (song, album or artist)

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Rate an item

Sets the caller's rating (0–5) on the item. The item type is detected from the id.

Authorizations:
BearerAuth
path Parameters
id
required
string

Item id (song, album or artist)

Request Body schema: application/json
required

Rating

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "error": {
    }
}

Clear an item's rating

Authorizations:
BearerAuth
path Parameters
id
required
string

Item id (song, album or artist)

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Rate an item

Sets the caller's rating (0–5) on the item. The item type is detected from the id.

Authorizations:
BearerAuth
path Parameters
id
required
string

Item id (song, album or artist)

Request Body schema: application/json
required

Rating

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "error": {
    }
}

favorites

Unfavorite an album

Authorizations:
BearerAuth
path Parameters
id
required
string

Album id

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Favorite an album

Authorizations:
BearerAuth
path Parameters
id
required
string

Album id

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Unfavorite an artist

Authorizations:
BearerAuth
path Parameters
id
required
string

Artist id

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Favorite an artist

Authorizations:
BearerAuth
path Parameters
id
required
string

Artist id

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Unfavorite a song

Authorizations:
BearerAuth
path Parameters
id
required
string

Track id

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Favorite a song

Authorizations:
BearerAuth
path Parameters
id
required
string

Track id

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

devices

Create a device session (issue a JWT)

Authenticates with username + password (or Subsonic token auth) and returns a device-session JWT carrying a unique id (jti). Use it as "Authorization: Bearer ". The session is tracked in the devices registry and can be revoked.

Request Body schema: application/json
required

Credentials

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "device": {
    },
  • "token": "string"
}

List devices

Lists the caller's active device sessions (one per issued JWT), with last-seen time, IP, user agent, and whether it's currently connected (seen recently).

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Revoke a device

Revokes a device session by id — the associated JWT can no longer authenticate.

Authorizations:
BearerAuth
path Parameters
id
required
string

Device id (jti) to revoke

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

discovery

Capability discovery

Unauthenticated. Lets clients detect supported immerle extensions and whether first-run setup is still needed.

Responses

Response samples

Content type
application/json
{
  • "capabilities": {
    },
  • "protocolVersion": "string",
  • "server": "string"
}

media

Cover art

Returns the cover image for a track or album id, optionally resized. The id "generator" instead builds a cover on the fly from its own query params (icon, title, subTitle, color, color2, angle); title/subTitle may be a known i18n key (e.g. "charts.top50") resolved via locale, or literal text.

Authorizations:
BearerAuth
path Parameters
id
required
string

Track/album id, or \

query Parameters
size
integer

Square size in pixels

locale
string

Label language for a generator cover's title/subTitle i18n keys (e.g. \

icon
string

Generator: Twemoji codepoint, e.g. \

title
string

Generator: title text or i18n key

subTitle
string

Generator: subtitle text or i18n key

color
string

Generator: background color, hex

color2
string

Generator: gradient end color, hex (empty = solid)

angle
number

Generator: gradient angle, degrees

Responses

Download a track

Serves a track's original audio bytes (no transcoding).

Authorizations:
BearerAuth
path Parameters
id
required
string

Track id

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Stream a track

Streams a track's audio. Supports HTTP range requests; maxBitRate/format transcode when set. Remote tracks are streamed progressively on first listen.

Authorizations:
BearerAuth
path Parameters
id
required
string

Track id

query Parameters
maxBitRate
integer

Transcode to at most this bit rate (kbps)

format
string

Transcode format (or 'raw' for original)

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Mint signed media URLs

Returns short-lived signed stream and download URLs for the track (usable as a plain media src). They expire after a few minutes.

Authorizations:
BearerAuth
path Parameters
id
required
string

Track id

Responses

Response samples

Content type
application/json
{
  • "download": "string",
  • "stream": "string"
}

playlists

Get (or create) the caller's Hall of Fame

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "changedAt": "string",
  • "createdAt": "string",
  • "tracks": [
    ]
}

Add a track to the Hall of Fame

Authorizations:
BearerAuth
Request Body schema: application/json
required

Track id

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "error": {
    }
}

Set the Hall of Fame's track order

Authorizations:
BearerAuth
Request Body schema: application/json
required

Track ids, in rank order

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "changedAt": "string",
  • "createdAt": "string",
  • "tracks": [
    ]
}

Set a Hall of Fame track's note

Authorizations:
BearerAuth
path Parameters
trackId
required
string

Track id

Request Body schema: application/json
required

Note

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "error": {
    }
}

Custom auto-generated playlists

Returns the caller's personal auto-generated playlists (top of the month, on repeat, forgotten favorites, random, recommended, made for you) that currently have at least one track, followed by the shared mood playlists when the sonic moods setting is on.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "playlists": [
    ]
}

Curated playlists for the caller

Returns the playlists made by people (not charts) that immerle discover matches to the caller's recent listening, refreshed daily. Empty when the admin turned the feature off.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "playlists": [
    ]
}

List playlists

Returns the playlists the caller owns, subscribes to or collaborates on.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "playlists": [
    ]
}

Create playlist

Authorizations:
BearerAuth
Request Body schema: application/json
required

Playlist

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "autoPlaylistKind": "string",
  • "changedAt": "string",
  • "collaborative": true,
  • "comment": "string",
  • "coverArt": "string",
  • "coverArts": [
    ],
  • "createdAt": "string",
  • "duration": 0,
  • "federated": true,
  • "id": "string",
  • "name": "string",
  • "owner": "string",
  • "public": true,
  • "songCount": 0,
  • "subscribed": true,
  • "tracks": [
    ]
}

Browse public playlists

Lists public playlists (not owned by the caller) available to subscribe to. Each entry includes whether the caller is already subscribed.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete playlist

Authorizations:
BearerAuth
path Parameters
id
required
string

Playlist id

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get playlist

Authorizations:
BearerAuth
path Parameters
id
required
string

Playlist id

Responses

Response samples

Content type
application/json
{
  • "autoPlaylistKind": "string",
  • "changedAt": "string",
  • "collaborative": true,
  • "comment": "string",
  • "coverArt": "string",
  • "coverArts": [
    ],
  • "createdAt": "string",
  • "duration": 0,
  • "federated": true,
  • "id": "string",
  • "name": "string",
  • "owner": "string",
  • "public": true,
  • "songCount": 0,
  • "subscribed": true,
  • "tracks": [
    ]
}

Update playlist

Edits metadata and appends/removes tracks. Owner/admin/collaborator only.

Authorizations:
BearerAuth
path Parameters
id
required
string

Playlist id

Request Body schema: application/json
required

Changes

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "error": {
    }
}

Add a playlist collaborator

Owner-only. Marks the playlist collaborative and grants edit rights to another user.

Authorizations:
BearerAuth
path Parameters
id
required
string

Playlist id

Request Body schema: application/json
required

User to grant edit rights

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "collaborator": "string"
}

Upload a playlist cover

Authorizations:
BearerAuth
path Parameters
id
required
string

Playlist id

Request Body schema:
required

Cover image (jpeg/png/gif/webp)

file (file)

Responses

Response samples

Content type
application/json
{
  • "autoPlaylistKind": "string",
  • "changedAt": "string",
  • "collaborative": true,
  • "comment": "string",
  • "coverArt": "string",
  • "coverArts": [
    ],
  • "createdAt": "string",
  • "duration": 0,
  • "federated": true,
  • "id": "string",
  • "name": "string",
  • "owner": "string",
  • "public": true,
  • "songCount": 0,
  • "subscribed": true,
  • "tracks": [
    ]
}

Generate a playlist cover

Authorizations:
BearerAuth
path Parameters
id
required
string

Playlist id

Request Body schema:

Cover spec (JSON, covergen.Spec) | Background image

One of
string (spec)

Responses

Response samples

Content type
application/json
{
  • "autoPlaylistKind": "string",
  • "changedAt": "string",
  • "collaborative": true,
  • "comment": "string",
  • "coverArt": "string",
  • "coverArts": [
    ],
  • "createdAt": "string",
  • "duration": 0,
  • "federated": true,
  • "id": "string",
  • "name": "string",
  • "owner": "string",
  • "public": true,
  • "songCount": 0,
  • "subscribed": true,
  • "tracks": [
    ]
}

Unsubscribe from a playlist

Authorizations:
BearerAuth
path Parameters
id
required
string

Playlist id

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Subscribe to a public playlist

Adds a public playlist to the caller's library (read-only). It then appears in getPlaylists like a normal playlist. Idempotent.

Authorizations:
BearerAuth
path Parameters
id
required
string

Playlist id to subscribe to

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Replace playlist tracks

Authorizations:
BearerAuth
path Parameters
id
required
string

Playlist id

Request Body schema: application/json
required

Track ids

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "autoPlaylistKind": "string",
  • "changedAt": "string",
  • "collaborative": true,
  • "comment": "string",
  • "coverArt": "string",
  • "coverArts": [
    ],
  • "createdAt": "string",
  • "duration": 0,
  • "federated": true,
  • "id": "string",
  • "name": "string",
  • "owner": "string",
  • "public": true,
  • "songCount": 0,
  • "subscribed": true,
  • "tracks": [
    ]
}

Resolve a federated playlist track for playback

Resolves an unresolved federated-playlist entry (checks the local catalog first, then the on-demand providers if enabled). 404 if it can't be resolved.

Authorizations:
BearerAuth
path Parameters
id
required
string

Playlist id

position
required
integer

Track position (0-based)

Responses

Response samples

Content type
application/json
{
  • "album": "string",
  • "albumId": "string",
  • "artist": "string",
  • "artistId": "string",
  • "bitRate": 0,
  • "bpm": 0,
  • "comment": "string",
  • "composer": "string",
  • "contentType": "string",
  • "coverArt": "string",
  • "duration": 0,
  • "genre": "string",
  • "id": "string",
  • "lyrics": "string",
  • "movementName": "string",
  • "movementNumber": 0,
  • "participants": [
    ],
  • "playCount": 0,
  • "rating": 0,
  • "remote": true,
  • "replayGainAlbum": 0,
  • "replayGainTrack": 0,
  • "size": 0,
  • "starred": "string",
  • "suffix": "string",
  • "title": "string",
  • "titleSort": "string",
  • "track": 0,
  • "unresolved": true,
  • "work": "string",
  • "year": 0
}

Open a Spotify playlist

Returns the local on-demand mirror of a public Spotify playlist (fetched from Spotify when missing or older than a week). Its tracks resolve lazily at play time like any federated playlist; subscribe to it to keep it in the library, refreshed weekly. 404 when the built-in spotify-playlist provider is disabled.

Authorizations:
BearerAuth
path Parameters
spotifyId
required
string

Spotify playlist id

Responses

Response samples

Content type
application/json
{
  • "autoPlaylistKind": "string",
  • "changedAt": "string",
  • "collaborative": true,
  • "comment": "string",
  • "coverArt": "string",
  • "coverArts": [
    ],
  • "createdAt": "string",
  • "duration": 0,
  • "federated": true,
  • "id": "string",
  • "name": "string",
  • "owner": "string",
  • "public": true,
  • "songCount": 0,
  • "subscribed": true,
  • "tracks": [
    ]
}

imports

List imports

Lists the caller's playlist imports (most recent first), without per-track items.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Start a playlist import

Queues an import of an external playlist (by source + reference). Returns the import job; poll GET /imports/{id} for progress. The import creates a new immerle playlist and resolves each source track against the on-demand content providers.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Import source + reference

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "createdAt": "string",
  • "doubtful": 0,
  • "error": "string",
  • "failed": 0,
  • "id": "string",
  • "items": [
    ],
  • "matched": 0,
  • "missing": 0,
  • "playlistId": "string",
  • "source": "string",
  • "sourcePlaylistName": "string",
  • "sourceRef": "string",
  • "status": "queued",
  • "total": 0,
  • "updatedAt": "string",
  • "userId": "string"
}

List import sources

Lists the available playlist-import sources (e.g. spotify) and whether each is configured.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Import status

Returns one import with its per-track items and their status (matched/doubtful/missing/failed) for a progress page.

Authorizations:
BearerAuth
path Parameters
id
required
string

Import id

Responses

Response samples

Content type
application/json
{
  • "createdAt": "string",
  • "doubtful": 0,
  • "error": "string",
  • "failed": 0,
  • "id": "string",
  • "items": [
    ],
  • "matched": 0,
  • "missing": 0,
  • "playlistId": "string",
  • "source": "string",
  • "sourcePlaylistName": "string",
  • "sourceRef": "string",
  • "status": "queued",
  • "total": 0,
  • "updatedAt": "string",
  • "userId": "string"
}

Validate or modify an import item

Resolves a doubtful/missing/failed import item: downloads a track and adds it to the import's playlist, flipping the item to "matched". With no query, it validates the flagged candidate as-is; with a query, it re-searches the content providers with that corrected text and uses the best result.

Authorizations:
BearerAuth
path Parameters
id
required
string

Import id

itemId
required
string

Import item id

Request Body schema: application/json

Optional corrected 'artist title' search

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "candidateCoverArt": "string",
  • "candidateTrackId": "string",
  • "confidence": 0,
  • "createdAt": "string",
  • "id": "string",
  • "importId": "string",
  • "matchedTrackId": "string",
  • "note": "string",
  • "position": 0,
  • "resolvedArtist": "string",
  • "resolvedTitle": "string",
  • "sourceAlbum": "string",
  • "sourceArtist": "string",
  • "sourceTitle": "string",
  • "status": "pending",
  • "updatedAt": "string"
}

jam

Create a Jam session

Authorizations:
BearerAuth
Request Body schema: application/json
required

Session name and initial track ids

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "participants": [
    ],
  • "session": {
    }
}

List the caller's pending Jam invites

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "invites": [
    ]
}

Dismiss a pending Jam invite

Authorizations:
BearerAuth
path Parameters
id
required
string

Invite id

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get the caller's hosted Jam session

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "participants": [
    ],
  • "session": {
    }
}

End a Jam session

Ends and removes the session. Host only.

Authorizations:
BearerAuth
path Parameters
id
required
string

Jam session id

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get Jam session state

Authorizations:
BearerAuth
path Parameters
id
required
string

Jam session id

Responses

Response samples

Content type
application/json
{
  • "participants": [
    ],
  • "session": {
    }
}

Update Jam playback (host only)

Host-only. Updates the shared track/position/state (partial) and broadcasts it to participants over SSE.

Authorizations:
BearerAuth
path Parameters
id
required
string

Jam session id

Request Body schema: application/json
required

Playback fields to change

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "participants": [
    ],
  • "session": {
    }
}

Stream Jam events (SSE)

Server-Sent Events stream. Emits the current state immediately, then a "state"/"participants"/"closed" event on every change.

Authorizations:
BearerAuth
path Parameters
id
required
string

Jam session id

Responses

Invite a user to a Jam session

Invites a user to the session. Host only; re-inviting just refreshes the invite.

Authorizations:
BearerAuth
path Parameters
id
required
string

Jam session id

Request Body schema: application/json
required

Invitee username

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "error": {
    }
}

Join a Jam session

Authorizations:
BearerAuth
path Parameters
id
required
string

Jam session id

Responses

Response samples

Content type
application/json
{
  • "participants": [
    ],
  • "session": {
    }
}

Leave a Jam session

Authorizations:
BearerAuth
path Parameters
id
required
string

Jam session id

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

library

List my uploaded tracks

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "songs": [
    ]
}

Library analytics

Returns library-wide analytics: artist/album/track counts, total on-disk size (bytes) and total duration (seconds). Cached and refreshed at each scan.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "albums": 0,
  • "artists": 0,
  • "totalDuration": 0,
  • "totalSize": 0,
  • "tracks": 0,
  • "updatedAt": "string"
}

Delete one of my uploaded tracks

Authorizations:
BearerAuth
path Parameters
id
required
string

Track id

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Rename one of my uploaded tracks

Authorizations:
BearerAuth
path Parameters
id
required
string

Track id

Request Body schema: application/json
required

New title

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "album": "string",
  • "albumId": "string",
  • "artist": "string",
  • "artistId": "string",
  • "bitRate": 0,
  • "bpm": 0,
  • "comment": "string",
  • "composer": "string",
  • "contentType": "string",
  • "coverArt": "string",
  • "duration": 0,
  • "genre": "string",
  • "id": "string",
  • "lyrics": "string",
  • "movementName": "string",
  • "movementNumber": 0,
  • "participants": [
    ],
  • "playCount": 0,
  • "rating": 0,
  • "remote": true,
  • "replayGainAlbum": 0,
  • "replayGainTrack": 0,
  • "size": 0,
  • "starred": "string",
  • "suffix": "string",
  • "title": "string",
  • "titleSort": "string",
  • "track": 0,
  • "unresolved": true,
  • "work": "string",
  • "year": 0
}

Replace the cover of one of my uploaded tracks

Authorizations:
BearerAuth
path Parameters
id
required
string

Track id

Request Body schema:
required

Cover image

file (file)

Responses

Response samples

Content type
application/json
{
  • "album": "string",
  • "albumId": "string",
  • "artist": "string",
  • "artistId": "string",
  • "bitRate": 0,
  • "bpm": 0,
  • "comment": "string",
  • "composer": "string",
  • "contentType": "string",
  • "coverArt": "string",
  • "duration": 0,
  • "genre": "string",
  • "id": "string",
  • "lyrics": "string",
  • "movementName": "string",
  • "movementNumber": 0,
  • "participants": [
    ],
  • "playCount": 0,
  • "rating": 0,
  • "remote": true,
  • "replayGainAlbum": 0,
  • "replayGainTrack": 0,
  • "size": 0,
  • "starred": "string",
  • "suffix": "string",
  • "title": "string",
  • "titleSort": "string",
  • "track": 0,
  • "unresolved": true,
  • "work": "string",
  • "year": 0
}

Upload an audio file

Ingests one audio file (max 200 MiB) into the catalog, owned by the caller.

Authorizations:
BearerAuth
Request Body schema:
required

Audio file

file (file)

Responses

Response samples

Content type
application/json
{
  • "album": "string",
  • "albumId": "string",
  • "artist": "string",
  • "artistId": "string",
  • "bitRate": 0,
  • "bpm": 0,
  • "comment": "string",
  • "composer": "string",
  • "contentType": "string",
  • "coverArt": "string",
  • "duration": 0,
  • "genre": "string",
  • "id": "string",
  • "lyrics": "string",
  • "movementName": "string",
  • "movementNumber": 0,
  • "participants": [
    ],
  • "playCount": 0,
  • "rating": 0,
  • "remote": true,
  • "replayGainAlbum": 0,
  • "replayGainTrack": 0,
  • "size": 0,
  • "starred": "string",
  • "suffix": "string",
  • "title": "string",
  • "titleSort": "string",
  • "track": 0,
  • "unresolved": true,
  • "work": "string",
  • "year": 0
}

users

Get your account

Returns the authenticated user's own account, including the private email.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "displayName": "string",
  • "email": "string",
  • "id": "string",
  • "isAdmin": true,
  • "language": "string",
  • "listenBrainzToken": "string",
  • "username": "string"
}

Update your account

Partial update — only fields present are changed. Lets a user set their display name, email and ListenBrainz token themselves.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Account fields to change

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "displayName": "string",
  • "email": "string",
  • "id": "string",
  • "isAdmin": true,
  • "language": "string",
  • "listenBrainzToken": "string",
  • "username": "string"
}

Disconnect Last.fm

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Last.fm connection status

Reports whether the caller has connected their Last.fm account.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "connected": true,
  • "username": "bob"
}

Finish connecting a Last.fm account

Exchanges a token approved via the auth URL for a permanent session key, and stores it on the caller's account. Returns 400 not_authorized if the token hasn't been approved yet.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Approved auth token

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "connected": true,
  • "username": "bob"
}

Start connecting a Last.fm account

Requests a fresh auth token and returns the URL the caller must open to approve it, the first step of Last.fm's desktop-auth handshake.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "authUrl": "string",
  • "token": "string"
}

List users

Returns every user's public identity (id, username, display name) so any authenticated caller can browse to a profile.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "users": [
    ]
}

User profile

Returns a user's profile — identity, recent activity visible to the caller (honoring privacy), their public playlists, all-time listening stats, and the top of their Hall of Fame (omitted when empty). Use "me" for the caller.

Authorizations:
BearerAuth
path Parameters
username
required
string

Target username, or 'me' for the caller

Responses

Response samples

Content type
application/json
{
  • "activity": [
    ],
  • "hallOfFame": {
    },
  • "isSelf": true,
  • "playlists": [
    ],
  • "stats": {
    },
  • "user": {
    }
}

Get a user's Hall of Fame

Authorizations:
BearerAuth
path Parameters
username
required
string

Target username, or 'me' for the caller

Responses

Response samples

Content type
application/json
{
  • "changedAt": "string",
  • "createdAt": "string",
  • "tracks": [
    ]
}

concerts

Your upcoming concert matches

Concert discovery matches your top-listened artists against Ticketmaster/Skiddle/Eventim near the admin-configured country, refreshed daily. Returns upcoming, non-dismissed matches, soonest first. Empty (not an error) when the feature is disabled, no country is configured, or nothing matched yet.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "concerts": [
    ]
}

Dismiss a concert match

Authorizations:
BearerAuth
path Parameters
id
required
string

Concert id

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

account

Change own password

Authorizations:
BearerAuth
Request Body schema: application/json
required

New password

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "error": {
    }
}

purchases

Disconnect Bandcamp

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Bandcamp connection status

Reports whether the caller has connected their Bandcamp account, and whether the stored cookie needs to be refreshed.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "connected": true,
  • "fanId": "string",
  • "lastSyncedAt": "2026-07-18T21:42:00Z",
  • "needsReconnect": true
}

List Bandcamp purchases

Fetches the caller's purchase collection live from Bandcamp. Each item is annotated with its import job status, if any.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Connect a Bandcamp account

Validates the pasted session cookie against Bandcamp and stores it (encrypted), replacing any previous connection.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Bandcamp session cookie

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "connected": true,
  • "fanId": "string",
  • "lastSyncedAt": "2026-07-18T21:42:00Z",
  • "needsReconnect": true
}

Import a Bandcamp purchase

Authorizations:
BearerAuth
path Parameters
saleItemType
required
string

Bandcamp sale item type

saleItemId
required
string

Bandcamp sale item id

Request Body schema: application/json
required

Item display fields

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "artistName": "string",
  • "attempts": 0,
  • "createdAt": "2026-07-18T21:42:00Z",
  • "error": "string",
  • "format": "flac",
  • "id": "string",
  • "itemTitle": "string",
  • "itemType": "album",
  • "saleItemId": "string",
  • "saleItemType": "string",
  • "status": "completed",
  • "trackIds": [
    ],
  • "updatedAt": "2026-07-18T21:43:00Z"
}

List Bandcamp import jobs

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "jobs": [
    ]
}

playback

Now playing

Returns the tracks every user is currently playing, newest first.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "nowPlaying": [
    ]
}

Get play queue

Returns the caller's saved cross-device play queue with its tracks.

Authorizations:
BearerAuth
query Parameters
deviceId
string

Polling device id, marked online (see targetOnline)

Responses

Response samples

Content type
application/json
{
  • "changedAt": "string",
  • "changedBy": "string",
  • "commandSeq": 0,
  • "current": "string",
  • "entries": [
    ],
  • "pendingCommand": {
    },
  • "playing": true,
  • "position": 0,
  • "repeat": "string",
  • "shuffle": true,
  • "targetDeviceId": "string",
  • "targetOnline": true
}

Save play queue

Replaces the caller's saved play queue (tracks, current track, position and playing state).

Authorizations:
BearerAuth
Request Body schema: application/json
required

Play queue

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "error": {
    }
}

Send a play-queue command

Sends a remote-control command (toggle, next, previous, seekTo, skipTo, toggleShuffle, cycleRepeat, playNext, enqueue, removeAt, move) for the active device (see targetDeviceId) to apply. Does not modify the saved queue state directly.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Command

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "error": {
    }
}

Stream play-queue events (SSE)

Server-Sent Events stream. Emits the current queue immediately, then again on every change (save, target change); also emits the caller's pending Jam invites (event "invites") on connect and whenever they change.

Authorizations:
BearerAuth
query Parameters
deviceId
string

Connecting device id, marked online while the stream is open (see targetOnline)

Responses

Set the active playback device

Assigns (or, with an empty deviceId, clears) the sole device that should be actively playing the caller's queue.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Target device

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "error": {
    }
}

List playback targets

Lists the caller's recently-active app installs (device-kind API tokens), for the "cast to device" picker.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

podcasts

List podcast channels

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "channels": [
    ]
}

Newest podcast episodes

Authorizations:
BearerAuth
query Parameters
count
integer

Max episodes (default 20)

Responses

Response samples

Content type
application/json
{
  • "episodes": [
    ]
}

Get a podcast episode

Authorizations:
BearerAuth
path Parameters
id
required
string

Episode id

Responses

Response samples

Content type
application/json
{
  • "channelId": "string",
  • "contentType": "string",
  • "description": "string",
  • "duration": 0,
  • "id": "string",
  • "publishDate": "string",
  • "size": 0,
  • "status": "string",
  • "streamable": true,
  • "suffix": "string",
  • "title": "string"
}

Download a podcast episode

Authorizations:
BearerAuth
path Parameters
id
required
string

Episode id

Responses

Response samples

Content type
application/json
{
  • "channelId": "string",
  • "contentType": "string",
  • "description": "string",
  • "duration": 0,
  • "id": "string",
  • "publishDate": "string",
  • "size": 0,
  • "status": "string",
  • "streamable": true,
  • "suffix": "string",
  • "title": "string"
}

Stream a podcast episode

Authorizations:
BearerAuth
path Parameters
id
required
string

Episode id

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get a podcast channel

Authorizations:
BearerAuth
path Parameters
id
required
string

Channel id

Responses

Response samples

Content type
application/json
{
  • "description": "string",
  • "episodes": [
    ],
  • "error": "string",
  • "id": "string",
  • "imageUrl": "string",
  • "status": "string",
  • "title": "string",
  • "url": "string"
}

radio

List internet radio stations

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "stations": [
    ]
}

Station logo

path Parameters
id
required
string

Station id

Responses

Unlike a radio station

Authorizations:
BearerAuth
path Parameters
id
required
string

Station id

Responses

Like a radio station

Authorizations:
BearerAuth
path Parameters
id
required
string

Station id

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

plays

Scrobble plays

Records playback for one or more tracks (now-playing + optional submission).

Authorizations:
BearerAuth
Request Body schema: application/json
required

Scrobble

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "error": {
    }
}

setup

First-run setup status

Unauthenticated. Reports whether the server still needs its first admin and whether a setup token is required.

Responses

Response samples

Content type
application/json
{
  • "initialized": true,
  • "needsSetup": true,
  • "setupTokenRequired": true,
  • "userCount": 0
}

Create the first administrator

Unauthenticated, one-shot. Creates the initial admin. Self-locks once any user exists (also true when the admin was instead bootstrapped from ADMIN_USERNAME/ADMIN_PASSWORD at startup).

Request Body schema: application/json
required

Initial admin credentials

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "displayName": "string",
  • "id": "string",
  • "isAdmin": true,
  • "username": "string"
}

shares

List shares

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "shares": [
    ]
}

Create share

Authorizations:
BearerAuth
Request Body schema: application/json
required

Share

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "createdAt": "string",
  • "description": "string",
  • "entries": [
    ],
  • "expiresAt": "string",
  • "id": "string",
  • "url": "string",
  • "viewCount": 0
}

Delete share

Authorizations:
BearerAuth
path Parameters
id
required
string

Share id

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Update share

Authorizations:
BearerAuth
path Parameters
id
required
string

Share id

Request Body schema: application/json
required

Changes

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "error": {
    }
}

smartPlaylists

List smart playlists

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "playlists": [
    ]
}

Create a smart playlist

Authorizations:
BearerAuth
Request Body schema: application/json
required

Name + rules

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "createdAt": "string",
  • "id": "string",
  • "name": "string",
  • "rules": {
    },
  • "updatedAt": "string"
}

Preview smart-playlist rules

Authorizations:
BearerAuth
Request Body schema: application/json
required

Rules to preview

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "songs": [
    ]
}

Delete a smart playlist

Authorizations:
BearerAuth
path Parameters
id
required
string

Smart playlist id

Responses

Update a smart playlist

Authorizations:
BearerAuth
path Parameters
id
required
string

Smart playlist id

Request Body schema: application/json
required

Name + rules

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "createdAt": "string",
  • "id": "string",
  • "name": "string",
  • "rules": {
    },
  • "updatedAt": "string"
}

Resolve a smart playlist's tracks

Authorizations:
BearerAuth
path Parameters
id
required
string

Smart playlist id

Responses

Response samples

Content type
application/json
{
  • "songs": [
    ]
}

browse

Auto-DJ order

Reorders tracks for smooth transitions from the local audio analysis: close tempos (a half or double tempo counts as close), harmonically compatible keys on the Camelot wheel, small energy jumps. Starts from ids[0] when keepFirst, else from the calmest track. Tracks not analyzed yet follow, in their original order. 404 when Auto-DJ is switched off.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Tracks to order

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "ids": [
    ]
}

Sonic radio

Tracks that sound like the seeds, from the local audio analysis: the closest analyzed tracks, at most two per artist, with a little randomness so two radios differ. A seed is a track, album or artist id; several seeds blend into one radio (e.g. the last tracks played, to extend a queue). 404 when both the sonic radio and autoplay are switched off; an empty list when none of the seeds is analyzed yet.

Authorizations:
BearerAuth
query Parameters
seed
required
Array of strings

Track, album or artist id (repeatable)

exclude
string

Comma-separated track ids to leave out (e.g. the current queue)

count
integer

Number of tracks (default 50, max 200)

Responses

Response samples

Content type
application/json
{
  • "songs": [
    ]
}

Track audio analysis

The tempo, key and energy the local audio analysis measured for a track (energy and danceability from 0 to 1). 404 when the analysis is switched off or the track isn't analyzed yet.

Authorizations:
BearerAuth
path Parameters
id
required
string

Track id

Responses

Response samples

Content type
application/json
{
  • "bpm": 127.6,
  • "camelot": "8A",
  • "danceability": 0.64,
  • "energy": 0.82,
  • "key": "A",
  • "mode": "minor"
}

theme

Get the UI theme

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "accentColor": "string"
}

Update the UI theme

Partial update — omitted fields keep their stored value; pass an empty accentColor to clear it.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Theme fields to change

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "accentColor": "string"
}

tokens

List API tokens

Lists the caller's active personal access tokens (no secrets).

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an API token

Creates a personal access token scoped to the caller. The secret is returned ONCE — store it now. Use it as "Authorization: Bearer ".

Authorizations:
BearerAuth
Request Body schema: application/json
required

Token name and optional expiry

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "prefix": "string",
  • "token": "string"
}

Revoke an API token

Authorizations:
BearerAuth
path Parameters
id
required
string

Token id to revoke

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

wrapped

Year-in-review ("Wrapped")

Returns the caller's listening stats for a calendar year: totals, top tracks/artists/genres and a per-month histogram. 404 when the feature is disabled.

Authorizations:
BearerAuth
query Parameters
year
integer

Calendar year (default: current)

Responses

Response samples

Content type
application/json
{
  • "byMonth": [
    ],
  • "topArtists": [
    ],
  • "topGenres": [
    ],
  • "topTracks": [
    ],
  • "totalPlays": 0,
  • "totalSeconds": 0,
  • "year": 0
}