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

1341 lines
24 KiB
Org Mode
Raw Blame History

#+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)
* Stream Queue Endpoints
** GET /api/asteroid/stream/queue
Get the current stream queue.
*** Authentication
Required (Admin role)
*** Response
#+BEGIN_SRC json
{
"status": "success",
"queue": [
{
"id": "track-id-123",
"title": "Track Name",
"artist": "Artist Name",
"path": "/path/to/file.mp3"
}
]
}
#+END_SRC
** POST /api/asteroid/stream/queue/add
Add a track to the stream queue.
*** Authentication
Required (Admin role)
*** Parameters
- =track-id= (required) - ID of the track to add
- =position= (optional) - Position in queue ("end" or index, default "end")
** POST /api/asteroid/stream/queue/remove
Remove a track from the stream queue.
*** Authentication
Required (Admin role)
*** Parameters
- =track-id= (required) - ID of the track to remove
** POST /api/asteroid/stream/queue/clear
Clear the entire stream queue.
*** Authentication
Required (Admin role)
** POST /api/asteroid/stream/queue/add-playlist
Add all tracks from a playlist to the stream queue.
*** Authentication
Required (Admin role)
*** Parameters
- =playlist-id= (required) - ID of the playlist to add
** POST /api/asteroid/stream/queue/reorder
Reorder tracks in the stream queue.
*** Authentication
Required (Admin role)
*** Parameters
- =track-ids= (required) - Ordered list of track IDs
** POST /api/asteroid/stream/queue/load-m3u
Load the stream queue from =playlists/stream-queue.m3u=.
*** Authentication
Required (Admin role)
* Recently Played Endpoints
** GET /api/asteroid/recently-played
Get recently played tracks.
*** Authentication
Not required
*** Parameters
- =mount= (optional) - Stream mount point (default: main stream)
*** Response
#+BEGIN_SRC json
{
"status": "success",
"tracks": [
{
"title": "Artist - Track Name",
"played_at": "2026-01-26T12:00:00Z"
}
]
}
#+END_SRC
* Playlist Scheduler Endpoints (Admin Only)
** GET /api/asteroid/scheduler/status
Get the current scheduler status.
*** Authentication
Required (Admin role)
*** Response
#+BEGIN_SRC json
{
"status": "success",
"enabled": true,
"current_playlist": "Asteroid-Low-Orbit.m3u",
"current_hour": 14,
"schedule": [
{"hour": 0, "playlist": "Late-Night.m3u"},
{"hour": 6, "playlist": "Morning.m3u"}
],
"available_playlists": ["Asteroid-Low-Orbit.m3u", "Late-Night.m3u"]
}
#+END_SRC
** POST /api/asteroid/scheduler/enable
Enable the playlist scheduler.
*** Authentication
Required (Admin role)
** POST /api/asteroid/scheduler/disable
Disable the playlist scheduler (stops automatic playlist changes).
*** Authentication
Required (Admin role)
** POST /api/asteroid/scheduler/load-current
Load the playlist for the current hour.
*** Authentication
Required (Admin role)
** GET /api/asteroid/scheduler/schedule
Get the full schedule.
*** Authentication
Required (Admin role)
** POST /api/asteroid/scheduler/update
Update a schedule entry.
*** Authentication
Required (Admin role)
*** Parameters
- =hour= (required) - Hour (0-23)
- =playlist= (required) - Playlist filename
** POST /api/asteroid/scheduler/remove
Remove a schedule entry.
*** Authentication
Required (Admin role)
*** Parameters
- =hour= (required) - Hour to remove from schedule
* Track Request Endpoints
** POST /api/asteroid/requests/submit
Submit a track request.
*** Authentication
Required
*** Parameters
- =title= (required) - Track title to request
- =message= (optional) - Message with the request
*** Response
#+BEGIN_SRC json
{
"status": "success",
"message": "Request submitted"
}
#+END_SRC
** GET /api/asteroid/requests/my
Get current user's requests.
*** Authentication
Required
*** Response
#+BEGIN_SRC json
{
"status": "success",
"requests": [
{
"id": 1,
"title": "Artist - Track",
"status": "pending",
"created_at": "2026-01-26T12:00:00Z"
}
]
}
#+END_SRC
** GET /api/asteroid/requests/recent
Get recently played requests (public).
*** Authentication
Not required
** GET /api/asteroid/admin/requests/pending
Get pending requests for admin review.
*** Authentication
Required (Admin role)
** GET /api/asteroid/admin/requests/list
Get requests by status.
*** Authentication
Required (Admin role)
*** Parameters
- =status= (optional) - Filter by status: "pending", "approved", "rejected", "played" (default: "pending")
** GET /api/asteroid/admin/requests/approved
Get approved requests ready to queue.
*** Authentication
Required (Admin role)
** POST /api/asteroid/admin/requests/approve
Approve a track request.
*** Authentication
Required (Admin role)
*** Parameters
- =id= (required) - Request ID
** POST /api/asteroid/admin/requests/reject
Reject a track request.
*** Authentication
Required (Admin role)
*** Parameters
- =id= (required) - Request ID
** POST /api/asteroid/admin/requests/play
Mark a request as played and add to queue.
*** Authentication
Required (Admin role)
*** Parameters
- =id= (required) - Request ID
* User Custom Playlist Endpoints
** GET /api/asteroid/library/browse
Browse the music library.
*** Authentication
Required
*** Parameters
- =search= (optional) - Search term
- =artist= (optional) - Filter by artist
- =album= (optional) - Filter by album
- =page= (optional) - Page number for pagination
** GET /api/asteroid/user/playlists
Get current user's custom playlists.
*** Authentication
Required
** GET /api/asteroid/user/playlists/get
Get a specific user playlist.
*** Authentication
Required
*** Parameters
- =id= (required) - Playlist ID
** POST /api/asteroid/user/playlists/create
Create a new user playlist.
*** Authentication
Required
*** Parameters
- =name= (required) - Playlist name
- =description= (optional) - Playlist description
** POST /api/asteroid/user/playlists/update
Update a user playlist.
*** Authentication
Required
*** Parameters
- =id= (required) - Playlist ID
- =name= (optional) - New name
- =description= (optional) - New description
- =tracks= (optional) - Updated track list
** POST /api/asteroid/user/playlists/submit
Submit a playlist for admin review.
*** Authentication
Required
*** Parameters
- =id= (required) - Playlist ID
** POST /api/asteroid/user/playlists/delete
Delete a user playlist.
*** Authentication
Required
*** Parameters
- =id= (required) - Playlist ID
** GET /api/asteroid/admin/user-playlists
Get all submitted user playlists for review.
*** Authentication
Required (Admin role)
** POST /api/asteroid/admin/user-playlists/review
Review a submitted playlist.
*** Authentication
Required (Admin role)
*** Parameters
- =id= (required) - Playlist ID
- =action= (required) - "approve" or "reject"
- =notes= (optional) - Review notes
** GET /api/asteroid/admin/user-playlists/preview
Preview a submitted playlist.
*** Authentication
Required (Admin role)
*** Parameters
- =id= (required) - Playlist ID
* User Favorites Endpoints
** GET /api/asteroid/user/favorites
Get current user's favorite tracks.
*** Authentication
Required
*** Response
#+BEGIN_SRC json
{
"status": "success",
"favorites": [
{
"track_id": 123,
"title": "Artist - Track",
"rating": 5,
"added_at": "2026-01-26T12:00:00Z"
}
]
}
#+END_SRC
** POST /api/asteroid/user/favorites/add
Add a track to favorites.
*** Authentication
Required
*** Parameters
- =track-id= (optional) - Track ID
- =title= (optional) - Track title (if track-id not provided)
- =rating= (optional) - Rating 1-5
** POST /api/asteroid/user/favorites/remove
Remove a track from favorites.
*** Authentication
Required
*** Parameters
- =track-id= (optional) - Track ID
- =title= (optional) - Track title (if track-id not provided)
** POST /api/asteroid/user/favorites/rate
Rate a favorite track.
*** Authentication
Required
*** Parameters
- =track-id= (required) - Track ID
- =rating= (required) - Rating 1-5
** GET /api/asteroid/user/favorites/check
Check if a track is in favorites.
*** Authentication
Required
*** Parameters
- =track-id= (required) - Track ID
*** Response
#+BEGIN_SRC json
{
"is_favorite": true,
"rating": 5
}
#+END_SRC
* User Listening History Endpoints
** GET /api/asteroid/user/history
Get current user's listening history.
*** Authentication
Required
** POST /api/asteroid/user/history/record
Record a track listen.
*** Authentication
Required
*** Parameters
- =track-id= (optional) - Track ID
- =title= (optional) - Track title
- =duration= (optional) - Listen duration in seconds
- =completed= (optional) - Whether track was completed (0 or 1)
** POST /api/asteroid/user/history/clear
Clear listening history.
*** Authentication
Required
** GET /api/asteroid/user/activity
Get listening activity data for charts.
*** Authentication
Required
*** Parameters
- =days= (optional) - Number of days to include (default: 30)
*** Response
#+BEGIN_SRC json
{
"status": "success",
"activity": [
{"date": "2026-01-26", "minutes": 120, "tracks": 25}
]
}
#+END_SRC
* User Profile Endpoints
** GET /api/asteroid/user/profile
Get current user's profile data.
*** Authentication
Required
*** Response
#+BEGIN_SRC json
{
"status": "success",
"user": {
"username": "user123",
"email": "user@example.com",
"role": "listener",
"avatar": "/avatars/user123.png",
"created_at": "2025-10-01T12:00:00Z"
}
}
#+END_SRC
** GET /api/asteroid/user/listening-stats
Get user's listening statistics.
*** Authentication
Required
** GET /api/asteroid/user/recent-tracks
Get user's recently listened tracks.
*** Authentication
Required
*** Parameters
- =limit= (optional) - Number of tracks (default: 3)
- =offset= (optional) - Offset for pagination (default: 0)
** GET /api/asteroid/user/top-artists
Get user's top artists.
*** Authentication
Required
*** Parameters
- =limit= (optional) - Number of artists (default: 5)
** POST /api/asteroid/user/avatar/upload
Upload a user avatar.
*** Authentication
Required
*** Request
Multipart form data with image file.
** GET /api/asteroid/user/avatar
Get current user's avatar URL.
*** Authentication
Required
* User Account Endpoints
** POST /api/asteroid/user/change-password
Change current user's password.
*** Authentication
Required
*** Parameters
- =current-password= (required) - Current password
- =new-password= (required) - New password
** POST /api/asteroid/admin/reset-password
Reset any user's password (admin only).
*** Authentication
Required (Admin role)
*** Parameters
- =username= (required) - Username
- =new-password= (required) - New password
** POST /api/asteroid/user/activate
Activate or deactivate a user account.
*** Authentication
Required (Admin role)
*** Parameters
- =user-id= (required) - User ID
- =active= (required) - "true" or "false"
** POST /api/asteroid/user/role
Change a user's role.
*** Authentication
Required (Admin role)
*** Parameters
- =user-id= (required) - User ID
- =role= (required) - New role ("admin", "dj", "listener")
** GET /api/asteroid/user-stats
Get user statistics (counts by role, active users, etc.).
*** Authentication
Required (Admin role)
* Frontend Partial Endpoints
These endpoints return HTML partials or JSON for frontend updates.
** GET /api/asteroid/partial/now-playing
Get HTML partial with current now-playing information.
*** Authentication
Not required
*** Parameters
- =mount= (optional) - Stream mount point
*** Response
HTML fragment for embedding in page.
** GET /api/asteroid/partial/now-playing-inline
Get inline text with now-playing info (for admin dashboard and widgets).
*** Authentication
Not required
*** Parameters
- =mount= (optional) - Stream mount point
*** Response
Plain text: "Artist - Track Title"
** GET /api/asteroid/partial/now-playing-json
Get JSON with now-playing info including track ID for favorites.
*** Authentication
Not required
*** Parameters
- =mount= (optional) - Stream mount point
*** Response
#+BEGIN_SRC json
{
"title": "Artist - Track Name",
"track_id": 123,
"listeners": 5
}
#+END_SRC
** GET /api/asteroid/channel-name
Get the current curated channel name.
*** Authentication
Not required
*** Response
#+BEGIN_SRC json
{
"channel": "Asteroid Low Orbit"
}
#+END_SRC
* 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.
* Utility Endpoints
** GET /api/asteroid/spectrum-analyzer.js
Get the dynamically generated JavaScript for the spectrum analyzer.
*** Authentication
Not required
*** Response
JavaScript code for the spectrum analyzer visualization.
* 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
Reference in New Issue View Git Blame Copy Permalink