maloja/API.md

Scrobbling

In order to scrobble from a wide selection of clients, you can use Maloja's standard-compliant APIs with the following settings:

GNU FM
Gnukebox URL	Your Maloja URL followed by /apis/audioscrobbler
Username	Doesn't matter
Password	Any of your API keys

ListenBrainz
API URL	Your Maloja URL followed by /apis/listenbrainz
Username	Doesn't matter
Auth Token	Any of your API keys

Audioscrobbler v1.2
Server URL	Your Maloja URL followed by /apis/audioscrobbler_legacy
Username	Doesn't matter
Password	Any of your API keys

Note that this is the base URL - some scrobblers ask you for the full endpoint instead.

API Documentation

The native Maloja API is reachable at /apis/mlj_1. Endpoints are listed on /api_explorer.

All endpoints return JSON data. POST request can be made with query string or form data arguments, but this is discouraged - JSON should be used whenever possible.

No application should ever rely on the non-existence of fields in the JSON data - i.e., additional fields can be added at any time without this being considered a breaking change. Existing fields should usually not be removed or changed, but it is always a good idea to add basic handling for missing fields.

General Structure

Most endpoints follow this structure:

Key	Type	Description
status	String	Status of the request. Can be success, ok, error, failure, no_operation
error	Mapping	Details about the error if one occured.
warnings	List	Any warnings that did not result in failure, but should be noted. Field is omitted if there are no warnings!
desc	String	Human-readable feedback. This can be shown directly to the user if desired.

Both errors and warnings have the following structure:

Key	Type	Description
type	String	Name of the error or warning type
value	varies	Specific data for this error or warning instance
desc	String	Human-readable error or warning description. This can be shown directly to the user if desired.

Entity Structure

Whenever a list of entities is returned, they have the following fields:

Scrobble

Key	Type	Description
time	Integer	Timestamp of the Scrobble in UTC
track	Mapping	The track being scrobbled
duration	Integer	How long the track was played for in seconds
origin	String	Client that submitted the scrobble, or import source

Example

{
  "time": 1650684324,
  "track": {
    "artists": ["Jennie Kim","HyunA","LE","SunMi"],
    "title": "Wow Thing",
    "length":200
  },
  "duration": 196,
  "origin": "client:navidrome_desktop"
}

Track

Key	Type	Description
artists	List	The artists credited with the track
title	String	The title of the track
length	Integer	The full length of the track in seconds

Example

{
  "artists": ["Blackpink","Chou Tzuyu"],
  "title": "MORE",
  "length": 171
}

Artist

Artists are just represented as raw Strings.

Example

"Red Velvet"