Radio Remote

Station

Station Collection

API Documentation

The Radio app provides a REST API to control playback and query information.

Authentication

If authentication is enabled in the app settings, you must include the pairing code in your requests:

  • HTTP Headers: Add X-Remote-Key: YOUR_CODE
  • Query Parameter: Add ?token=YOUR_CODE (fallback for images and WebSockets)

API Reference

GET /api/status

Returns current playback status. Recommended for initial state only; use WebSockets for real-time updates.

Response Example:
{
  "isPlaying": true,
  "playWhenReady": true,
  "playbackState": 3,
  "currentStationUuid": "fc080549-...",
  "metadata": "Artist - Title",
  "starred": true
}                   

WS /api/updates

WebSocket endpoint for real-time status updates. Pushes status objects whenever state or metadata changes.

Example Usage (JavaScript):
const token = '123456'; // From app settings
const socket = new WebSocket('ws://' + location.host + '/api/updates?token=' + token);
socket.onmessage = (event) => {
  const status = JSON.parse(event.data);
  console.log('Update received:', status);
};                      

GET /api/stations

Returns all stations in collection.

Response Example:
[
  {
    "uuid": "fc080549-...",
    "name": "Station Name",
    "hasImage": true,
    "starred": true
  }
]                   

GET /api/image/{uuid}

Returns the image for a specific station. Supports HTTP caching via ETag and If-None-Match.

Response: Image (binary data, JPEG)

GET /api/config

Returns the app version.

Response Example:
{ "version": "15.1" }

POST /api/play/{uuid}

Starts playback of a specific station.

Response Example:
{ "status": "ok" }

POST /api/pause

Pauses current playback.

Response Example:
{ "status": "ok" }

POST /api/resume

Resumes current playback.

Response Example:
{ "status": "ok" }

POST /api/next

Plays the next station.

Response Example:
{ "status": "ok" }

POST /api/prev

Plays the previous station.

Response Example:
{ "status": "ok" }