glenn
/
asteroid
mirror of https://github.com/glenneth1/asteroid.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
asteroid/docs/API-ENDPOINTS.org

12 KiB
Raw Blame History

Asteroid Radio - API Endpoints Reference

Overview

Asteroid Radio provides a comprehensive JSON API built with Radiance's define-api framework. All API endpoints return JSON responses and follow RESTful conventions.

Base URL

All API endpoints are prefixed with /api/asteroid/

Authentication

Protected endpoints require user authentication via session cookies. Unauthenticated requests to protected endpoints will return an error response.

Response Format

All API responses follow this structure:

{
  "status": "success" | "error",
  "message": "Human-readable message",
  "data": { ... }  // Optional, endpoint-specific data
}

Status Endpoints

GET /api/asteroid/status

Get server status and system information.

Authentication

Not required

Response 

{
  "status": "success",
  "server": "asteroid-radio",
  "version": "1.0",
  "uptime": 3600
}

GET /api/asteroid/auth-status

Check current authentication status.

Authentication

Not required

Response 

{
  "loggedIn": true,
  "username": "admin",
  "role": "admin"
}

GET /api/asteroid/icecast-status

Get Icecast streaming server status and current track information.

Authentication

Not required

Response 

{
  "icestats": {
    "source": {
      "title": "Artist - Track Name",
      "listeners": 5,
      "genre": "Electronic",
      "bitrate": 128
    }
  }
}

Track Endpoints

GET /api/asteroid/tracks

Get list of all tracks in the music library.

Authentication

Required

Response 

{
  "status": "success",
  "tracks": [
    {
      "id": "track-id-123",
      "title": "Track Name",
      "artist": "Artist Name",
      "album": "Album Name",
      "duration": 245,
      "format": "mp3"
    }
  ]
}

GET /api/asteroid/admin/tracks

Get administrative track listing (admin only).

Authentication

Required (Admin role)

Response

Same as /api/asteroid/tracks but includes additional metadata for administration.

Player Control Endpoints

GET /api/asteroid/player/status

Get current player status.

Authentication

Required

Response 

{
  "status": "success",
  "player": {
    "state": "playing" | "paused" | "stopped",
    "currentTrack": {
      "id": "track-id-123",
      "title": "Track Name",
      "artist": "Artist Name"
    },
    "position": 45,
    "duration": 245
  }
}

POST /api/asteroid/player/play

Play a specific track.

Authentication

Required

Parameters

  • track-id (required) - ID of the track to play

Example Request 

curl -X POST http://localhost:8080/api/asteroid/player/play \
  -d "track-id=track-id-123"

Response 

{
  "status": "success",
  "message": "Playing track",
  "player": {
    "state": "playing",
    "currentTrack": { ... }
  }
}

POST /api/asteroid/player/pause

Pause current playback.

Authentication

Required

Response 

{
  "status": "success",
  "message": "Playback paused",
  "player": {
    "state": "paused"
  }
}

POST /api/asteroid/player/stop

Stop current playback.

Authentication

Required

Response 

{
  "status": "success",
  "message": "Playback stopped",
  "player": {
    "state": "stopped"
  }
}

POST /api/asteroid/player/resume

Resume paused playback.

Authentication

Required

Response 

{
  "status": "success",
  "message": "Playback resumed",
  "player": {
    "state": "playing"
  }
}

Playlist Endpoints

GET /api/asteroid/playlists

Get all playlists for the current user.

Authentication

Required

Response 

{
  "status": "success",
  "playlists": [
    {
      "id": "playlist-id-123",
      "name": "My Playlist",
      "description": "Favorite tracks",
      "trackCount": 15,
      "created": "2025-10-10T12:00:00Z"
    }
  ]
}

POST /api/asteroid/playlists/create

Create a new playlist.

Authentication

Required

Parameters

  • name (required) - Playlist name
  • description (optional) - Playlist description

Example Request 

curl -X POST http://localhost:8080/api/asteroid/playlists/create \
  -d "name=My Playlist&description=Favorite tracks"

Response 

{
  "status": "success",
  "message": "Playlist created successfully",
  "playlist": {
    "id": "playlist-id-123",
    "name": "My Playlist",
    "description": "Favorite tracks"
  }
}

GET /api/asteroid/playlists/get

Get details of a specific playlist.

Authentication

Required

Parameters

  • playlist-id (required) - ID of the playlist

Example Request 

curl "http://localhost:8080/api/asteroid/playlists/get?playlist-id=playlist-id-123"

Response 

{
  "status": "success",
  "playlist": {
    "id": "playlist-id-123",
    "name": "My Playlist",
    "description": "Favorite tracks",
    "tracks": [
      {
        "id": "track-id-123",
        "title": "Track Name",
        "artist": "Artist Name"
      }
    ]
  }
}

POST /api/asteroid/playlists/add-track

Add a track to a playlist.

Authentication

Required

Parameters

  • playlist-id (required) - ID of the playlist
  • track-id (required) - ID of the track to add

Example Request 

curl -X POST http://localhost:8080/api/asteroid/playlists/add-track \
  -d "playlist-id=playlist-id-123&track-id=track-id-456"

Response 

{
  "status": "success",
  "message": "Track added to playlist"
}

POST /api/asteroid/playlists/remove-track

Remove a track from a playlist.

Authentication

Required

Parameters

  • playlist-id (required) - ID of the playlist
  • track-id (required) - ID of the track to remove

Response 

{
  "status": "success",
  "message": "Track removed from playlist"
}

POST /api/asteroid/playlists/delete

Delete a playlist.

Authentication

Required

Parameters

  • playlist-id (required) - ID of the playlist

Response 

{
  "status": "success",
  "message": "Playlist deleted"
}

Admin Endpoints

POST /api/asteroid/admin/scan-library

Scan the music library for new tracks.

Authentication

Required (Admin role)

Response 

{
  "status": "success",
  "message": "Library scan completed",
  "tracks-added": 42
}

GET /api/asteroid/users

Get all users.

Authentication

Required (Admin role)

Response

Returns a JSON object with a users array.

POST /api/asteroid/users/create

Create a new user.

Authentication

Required (Admin role)

Parameters

  • username (required)
  • email (required)
  • password (required)
  • role (required)

Response

Returns a JSON object indicating success or failure.

Stream Playlist File Endpoints (Admin Only)

These endpoints manage playlist files in the playlists/ directory, and control the currently active playlists/stream-queue.m3u.

GET /api/asteroid/stream/playlists

List available playlist files in playlists/ (excluding stream-queue.m3u).

Authentication

Required (Admin role)

Response

Returns a JSON object with a playlists array of filenames.

POST /api/asteroid/stream/playlists/load

Load a playlist file into playlists/stream-queue.m3u and return its paths.

Authentication

Required (Admin role)

Parameters

  • name (required) - Playlist filename to load

POST /api/asteroid/stream/playlists/save

Save the in-memory stream queue to playlists/stream-queue.m3u.

Authentication

Required (Admin role)

POST /api/asteroid/stream/playlists/save-as

Save the current stream queue to a new playlist file.

Authentication

Required (Admin role)

Parameters

  • name (required) - New playlist filename (.m3u suffix is optional)

POST /api/asteroid/stream/playlists/clear

Clear playlists/stream-queue.m3u and empty the in-memory stream queue.

Authentication

Required (Admin role)

GET /api/asteroid/stream/playlists/current

Return the current playlists/stream-queue.m3u contents with best-effort track info.

Authentication

Required (Admin role)

Liquidsoap Control Endpoints (Admin Only)

GET /api/asteroid/liquidsoap/status

Get Liquidsoap status including uptime, current metadata, and remaining time.

Authentication

Required (Admin role)

POST /api/asteroid/liquidsoap/skip

Skip the current track in the stream queue.

Authentication

Required (Admin role)

POST /api/asteroid/liquidsoap/reload

Force Liquidsoap to reload the playlist.

Authentication

Required (Admin role)

POST /api/asteroid/liquidsoap/restart

Restart the Liquidsoap Docker container.

Authentication

Required (Admin role)

POST /api/asteroid/icecast/restart

Restart the Icecast Docker container.

Authentication

Required (Admin role)

Listener Statistics Endpoints

GET /api/asteroid/stats/current

Get the current listener statistics.

Authentication

Not required

GET /api/asteroid/stats/daily

Get the daily listener statistics.

Authentication

Required (Admin role)

Response

Returns a JSON object containing daily listener statistics.

GET /api/asteroid/stats/geo

Get the geographical listener statistics.

Authentication

Required (Admin role)

Response

Returns a JSON object containing geographical listener statistics.

GET /api/asteroid/stats/geo/cities

Get the listener statistics by city.

Authentication

Required (Admin role)

Response

Returns a JSON object containing the country and a cities array with per-city aggregates.

Error Responses

All endpoints may return error responses in this format:

{
  "status": "error",
  "message": "Description of the error"
}

Common HTTP Status Codes

  • 200 - Success
  • 400 - Bad Request (missing or invalid parameters)
  • 401 - Unauthorized (authentication required)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Not Found (resource doesn't exist)
  • 500 - Internal Server Error

Testing API Endpoints

Using curl 

# Get server status
curl http://localhost:8080/api/asteroid/status

# Get auth status
curl http://localhost:8080/api/asteroid/auth-status

# Get tracks (requires authentication)
curl -b cookies.txt http://localhost:8080/api/asteroid/tracks

# Play a track
curl -X POST -b cookies.txt http://localhost:8080/api/asteroid/player/play \
  -d "track-id=123"

Using the Test Suite

The project includes a comprehensive test suite:

./test-server.sh

See docs/TESTING.org for details.

Browser Detection

API endpoints support a browser parameter for dual usage (API + browser):

# API usage - returns JSON
curl -X POST http://localhost:8080/api/asteroid/playlists/create \
  -d "name=Test"

# Browser usage - redirects to page
curl -X POST http://localhost:8080/api/asteroid/playlists/create \
  -d "name=Test&browser=true"

When browser=true is passed, endpoints will redirect to appropriate pages instead of returning JSON.

Rate Limiting

API endpoints implement rate limiting to prevent abuse. Excessive requests may result in temporary blocking.

Future Enhancements

Planned API improvements:

  • WebSocket support for real-time updates
  • Pagination for large result sets
  • Advanced search and filtering
  • Batch operations
  • API versioning
  • OAuth2 authentication option