asteroid/docs/API-ENDPOINTS.org

#+TITLE: Asteroid Radio - API Endpoints Reference
#+AUTHOR: Asteroid Radio Development Team
#+DATE: 2026-01-26

* 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:

#+BEGIN_SRC json
{
  "status": "success" | "error",
  "message": "Human-readable message",
  "data": { ... }  // Optional, endpoint-specific data
}
#+END_SRC

* Status Endpoints

** GET /api/asteroid/status

Get server status and system information.

*** Authentication
Not required

*** Response
#+BEGIN_SRC json
{
  "status": "success",
  "server": "asteroid-radio",
  "version": "1.0",
  "uptime": 3600
}
#+END_SRC

** GET /api/asteroid/auth-status

Check current authentication status.

*** Authentication
Not required

*** Response
#+BEGIN_SRC json
{
  "loggedIn": true,
  "username": "admin",
  "role": "admin"
}
#+END_SRC

** GET /api/asteroid/icecast-status

Get Icecast streaming server status and current track information.

*** Authentication
Not required

*** Response
#+BEGIN_SRC json
{
  "icestats": {
    "source": {
      "title": "Artist - Track Name",
      "listeners": 5,
      "genre": "Electronic",
      "bitrate": 128
    }
  }
}
#+END_SRC

* Track Endpoints

** GET /api/asteroid/tracks

Get list of all tracks in the music library.

*** Authentication
Required

*** Response
#+BEGIN_SRC json
{
  "status": "success",
  "tracks": [
    {
      "id": "track-id-123",
      "title": "Track Name",
      "artist": "Artist Name",
      "album": "Album Name",
      "duration": 245,
      "format": "mp3"
    }
  ]
}
#+END_SRC

** 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
#+BEGIN_SRC json
{
  "status": "success",
  "player": {
    "state": "playing" | "paused" | "stopped",
    "currentTrack": {
      "id": "track-id-123",
      "title": "Track Name",
      "artist": "Artist Name"
    },
    "position": 45,
    "duration": 245
  }
}
#+END_SRC

** POST /api/asteroid/player/play

Play a specific track.

*** Authentication
Required

*** Parameters
- =track-id= (required) - ID of the track to play

*** Example Request
#+BEGIN_SRC bash
curl -X POST http://localhost:8080/api/asteroid/player/play \
  -d "track-id=track-id-123"
#+END_SRC

*** Response
#+BEGIN_SRC json
{
  "status": "success",
  "message": "Playing track",
  "player": {
    "state": "playing",
    "currentTrack": { ... }
  }
}
#+END_SRC

** POST /api/asteroid/player/pause

Pause current playback.

*** Authentication
Required

*** Response
#+BEGIN_SRC json
{
  "status": "success",
  "message": "Playback paused",
  "player": {
    "state": "paused"
  }
}
#+END_SRC

** POST /api/asteroid/player/stop

Stop current playback.

*** Authentication
Required

*** Response
#+BEGIN_SRC json
{
  "status": "success",
  "message": "Playback stopped",
  "player": {
    "state": "stopped"
  }
}
#+END_SRC

** POST /api/asteroid/player/resume

Resume paused playback.

*** Authentication
Required

*** Response
#+BEGIN_SRC json
{
  "status": "success",
  "message": "Playback resumed",
  "player": {
    "state": "playing"
  }
}
#+END_SRC

* Playlist Endpoints

** GET /api/asteroid/playlists

Get all playlists for the current user.

*** Authentication
Required

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

** POST /api/asteroid/playlists/create

Create a new playlist.

*** Authentication
Required

*** Parameters
- =name= (required) - Playlist name
- =description= (optional) - Playlist description

*** Example Request
#+BEGIN_SRC bash
curl -X POST http://localhost:8080/api/asteroid/playlists/create \
  -d "name=My Playlist&description=Favorite tracks"
#+END_SRC

*** Response
#+BEGIN_SRC json
{
  "status": "success",
  "message": "Playlist created successfully",
  "playlist": {
    "id": "playlist-id-123",
    "name": "My Playlist",
    "description": "Favorite tracks"
  }
}
#+END_SRC

** GET /api/asteroid/playlists/get

Get details of a specific playlist.

*** Authentication
Required

*** Parameters
- =playlist-id= (required) - ID of the playlist

*** Example Request
#+BEGIN_SRC bash
curl "http://localhost:8080/api/asteroid/playlists/get?playlist-id=playlist-id-123"
#+END_SRC

*** Response
#+BEGIN_SRC json
{
  "status": "success",
  "playlist": {
    "id": "playlist-id-123",
    "name": "My Playlist",
    "description": "Favorite tracks",
    "tracks": [
      {
        "id": "track-id-123",
        "title": "Track Name",
        "artist": "Artist Name"
      }
    ]
  }
}
#+END_SRC

** 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
#+BEGIN_SRC bash
curl -X POST http://localhost:8080/api/asteroid/playlists/add-track \
  -d "playlist-id=playlist-id-123&track-id=track-id-456"
#+END_SRC

*** Response
#+BEGIN_SRC json
{
  "status": "success",
  "message": "Track added to playlist"
}
#+END_SRC

** 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
#+BEGIN_SRC json
{
  "status": "success",
  "message": "Track removed from playlist"
}
#+END_SRC

** POST /api/asteroid/playlists/delete

Delete a playlist.

*** Authentication
Required

*** Parameters
- =playlist-id= (required) - ID of the playlist

*** Response
#+BEGIN_SRC json
{
  "status": "success",
  "message": "Playlist deleted"
}
#+END_SRC

* Admin Endpoints

** POST /api/asteroid/admin/scan-library

Scan the music library for new tracks.

*** Authentication
Required (Admin role)

*** Response
#+BEGIN_SRC json
{
  "status": "success",
  "message": "Library scan completed",
  "tracks-added": 42
}
#+END_SRC

** 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:

#+BEGIN_SRC json
{
  "status": "error",
  "message": "Description of the error"
}
#+END_SRC

** 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

#+BEGIN_SRC bash
# 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"
#+END_SRC

** Using the Test Suite

The project includes a comprehensive test suite:

#+BEGIN_SRC bash
./test-server.sh
#+END_SRC

See =docs/TESTING.org= for details.

* Browser Detection

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

#+BEGIN_SRC bash
# 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"
#+END_SRC

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