RESTful interface

GET /metadata_log

Without parameters, GET /metadata_log returns the 10 most recent metadata items played. The following query parameters can be provided

Query Parameters

  • start (string) – (ISO 8601 format) define an inclusive query interval

  • end (string) – define an inclusive query interval

  • limit (int) – restricts the number of results (and defaults to 10). It is ignored if start and end are provided.

  • chronological (bool) – may be set to anything non-empty (use 1 or true), otherwise results are sorted recent first. Doesn’t affect the interpretation of start and end.

Response JSON Object

  • metadata_log – logged metadata matching the query parameters.

POST /metadata_log

Should be called by Liquidsoap to save tracks’ metadata. See Logging metadata.

POST /login

Should be called by Liquidsoap to authenticate harbor users. It returns the matched user information as a JSONobject, or a 404 error. See Authenticating users on harbor.

GET /users
Response JSON Array of Objects

  • username –

  • created_at –

  • modified_at –

PUT /users

User registration

Request JSON Object

  • username –

  • password –

Response JSON Object

  • username –

  • created_at –

  • modified_at –

POST /users/(username)

Update user attributes

Request JSON Object

  • password – optional

Response JSON Object

  • username –

  • created_at –

  • modified_at –

DELETE /users/(username)

Delete someone’s user account

Response JSON Object

  • deleted – username

GET /live

The returned JSON object might contain many more fields, depending on what’s in the current track’s metadata. You can reasonably expect title and artist.

Response JSON Object

  • source – name of the currently playing source

  • on_air – current track start time

  • status – status of the current source (“playing” or “connected to …”)

  • server_time – server’s datetime

  • remaining – maybe remaining duration of current source, in seconds

GET /parameters

This returns values from the [interface] section of the configuration file.

Response JSON Object

  • name – instance name (appears as interface’s title)

  • version – showergel’s version

  • commands – list of available Liquidsoap commands

DELETE /live

Skips current track: this sends a skip command to the first Liquidsoap output.

PUT /schedule

Schedule event creation. Note that at most one event can be registered at a given date.

Request JSON Object

  • command – Liquidsoap command

  • when – Event time (ISO 8601 with time zone info)

Response JSON Object

  • event_id – created event’s ID

GET /schedule
List upcoming events. For each event, expect:

  • event_id

  • when (ISO 8601)

  • command

Response JSON Object

  • schedule – list of scheduled events

OPTIONS /(:re:.*)

this only ensures we support OPTIONS requests (instead of returning 405). CORS headers will be returned iff send_cors is enabled.