API Reference v1

Complete reference for the Aaxion REST API.

Base URL

http://localhost:8080/api/v1

Auth Header

Bearer <token>

Authentication

POST/api/v1/auth/registerPUBLIC

Register the initial admin user. Fails if a user already exists.

curl -X POST \
  -d '{"username":"admin","password":"mypassword"}' \
  http://localhost:8080/api/v1/auth/register
POST/api/v1/auth/login

Authenticate and receive a session token and device info.

curl -X POST \
  -d '{"username":"admin","password":"mypassword"}' \
  http://localhost:8080/api/v1/auth/login
POST/api/v1/auth/logout

Invalidate the current session token.

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  http://localhost:8080/api/v1/auth/logout
POST/api/v1/auth/token/generate

Generate a new short-lived access token (5 hours). Requires session token, not access token.

curl -X POST \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  http://localhost:8080/api/v1/auth/token/generate
POST/api/v1/auth/token/remove

Remove all access tokens for a given token.

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"token":"token_to_clean"}' \
  http://localhost:8080/api/v1/auth/token/remove

Files & Directories

GET/api/v1/files/view?dir={path}

List contents of a directory. Returns files and folders as JSON.

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8080/api/v1/files/view?dir=/home/user"
POST/api/v1/files/directory/create?path={path}

Create a new directory at the specified path.

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8080/api/v1/files/directory/create?path=/home/user/new_folder"
POST/api/v1/files/unzip

Extract a ZIP archive. If dest_dir is omitted, it extracts to the zip's folder.

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"zip_path":"/home/user/archive.zip","dest_dir":"/home/user/output"}' \
  http://localhost:8080/api/v1/files/unzip

Upload & Download

POST/api/v1/files/upload?dir={path}

Upload a single file via multipart/form-data. Field name: file.

curl -F "file=@/path/to/file.txt" \
  -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8080/api/v1/files/upload?dir=/home/user"
GET/api/v1/files/download?path={file}

Download a file. Supports token via ?tkn= query param.

curl -O \
  -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8080/api/v1/files/download?path=/home/user/file.txt"

Chunked Uploads

Three-step flow for multi-GB files: initialize, stream parts, then merge.

POST/api/v1/files/upload/chunk/start?filename={name}

Step 1 — Initialize a chunked upload session.

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8080/api/v1/files/upload/chunk/start?filename=big.zip"
POST/api/v1/files/upload/chunk?filename={name}&chunk_index={idx}

Step 2 — Upload a single binary chunk (raw body, NOT multipart). Keep under 90MB.

curl --data-binary @part0.bin \
  -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8080/api/v1/files/upload/chunk?filename=big.zip&chunk_index=0"
POST/api/v1/files/upload/chunk/complete?filename={name}&dir={path}

Step 3 — Merge all chunks into the final file.

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8080/api/v1/files/upload/chunk/complete?filename=big.zip&dir=/home/user"

Media & Images

GET/api/v1/images/thumbnail?path={file}

Get a resized 200px JPEG thumbnail. Supports ?tkn=<token> for img tags.

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8080/api/v1/images/thumbnail?path=/home/user/photo.jpg"
GET/api/v1/images/view?path={file}

Full-resolution image with 7-day client-side cache. Supports ?tkn= query param.

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8080/api/v1/images/view?path=/home/user/photo.jpg"
GET/api/v1/files/stream?path={file}

Zero-buffer stream a video or audio file. Supports HTTP Range for seeking and ?tkn= query param.

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8080/api/v1/files/stream?path=/home/user/video.mp4"

Temporary Sharing

GET/api/v1/share/temp/request?file_path={path}PUBLIC

Generate a one-time temporary download link.

curl "http://localhost:8080/api/v1/share/temp/request?file_path=/home/user/file.zip"
GET/api/v1/share/temp/{token}PUBLIC

Download via one-time token. No auth required. Token is consumed after use.

curl -O "http://localhost:8080/api/v1/share/temp/abcdef123456"

Anonymous Uploads

Token-based uploads for external users. Admin generates tokens, guests upload with them.

POST/api/v1/anonymous/token/generate

Admin: Create a new upload token. Configure via query params.

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8080/api/v1/anonymous/token/generate?target_dir=/uploads&max_uploads=5&expiry_hours=48&max_file_size=1073741824"
POST/api/v1/anonymous/token/revoke?token={token}

Admin: Revoke an existing upload token.

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8080/api/v1/anonymous/token/revoke?token=abc123"
GET/api/v1/anonymous/tokens

Admin: List all active upload tokens.

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8080/api/v1/anonymous/tokens
GET/api/v1/anonymous/token/info?token={token}

Admin: Get details about a specific upload token.

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8080/api/v1/anonymous/token/info?token=abc123"
POST/api/v1/anonymous/token/validate?token={token}PUBLIC

Guest: Check if a token is valid before uploading.

curl -X POST "http://localhost:8080/api/v1/anonymous/token/validate?token=abc123"
POST/api/v1/anonymous/upload?token={token}PUBLIC

Guest: Upload a file using a valid upload token.

curl -F "file=@/path/to/file.txt" \
  "http://localhost:8080/api/v1/anonymous/upload?token=abc123"
POST/api/v1/anonymous/upload/chunk/start?token={token}&filename={name}PUBLIC

Guest: Start chunked upload with token.

curl -X POST \
  "http://localhost:8080/api/v1/anonymous/upload/chunk/start?token=abc123&filename=big.zip"
POST/api/v1/anonymous/upload/chunk?token={token}&filename={name}&chunk_index={idx}PUBLIC

Guest: Upload a binary chunk.

curl --data-binary @part0.bin \
  "http://localhost:8080/api/v1/anonymous/upload/chunk?token=abc123&filename=big.zip&chunk_index=0"
POST/api/v1/anonymous/upload/chunk/complete?token={token}&filename={name}PUBLIC

Guest: Complete chunked upload.

curl -X POST \
  "http://localhost:8080/api/v1/anonymous/upload/chunk/complete?token=abc123&filename=big.zip"

System

GET/api/v1/system/infoPUBLIC

Server version, codename, OS, architecture. No auth required.

curl http://localhost:8080/api/v1/system/info
GET/api/v1/system/root-path

Get the monitored root directory.

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8080/api/v1/system/root-path
GET/api/v1/system/storage

Disk usage statistics including external devices.

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8080/api/v1/system/storage

Movies

Legacy endpoints. Not actively developed.

GET/api/v1/movies

List all movies.

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8080/api/v1/movies
GET/api/v1/movies/search?q={query}

Search movies by title or description.

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8080/api/v1/movies/search?q=inter"
POST/api/v1/movies/add

Add a new movie entry.

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"title":"Interstellar","file_path":"/media/movies/interstellar.mp4","file_id":10,"description":"A great movie","poster_path":"/media/posters/interstellar.jpg"}' \
  http://localhost:8080/api/v1/movies/add
PUT/api/v1/movies/edit

Edit an existing movie.

curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"id":1,"title":"Updated Title","description":"Updated description","poster_path":"/media/posters/updated.jpg"}' \
  http://localhost:8080/api/v1/movies/edit
GET/api/v1/movies/stream?id={id}

Stream a movie. Supports HTTP Range and ?tkn= query param.

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8080/api/v1/movies/stream?id=1"

Series & Episodes

Legacy endpoints. Not actively developed.

GET/api/v1/series

List all series.

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8080/api/v1/series
GET/api/v1/series/search?q={query}

Search series by title.

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8080/api/v1/series/search?q=breaking"
POST/api/v1/series/add

Create a new series.

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"title":"Stranger Things","description":"Sci-fi horror drama."}' \
  http://localhost:8080/api/v1/series/add
PUT/api/v1/series/edit

Edit an existing series.

curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"id":1,"title":"Updated Title","description":"Updated description"}' \
  http://localhost:8080/api/v1/series/edit
GET/api/v1/series/episodes?series_id={id}

List episodes for a series.

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8080/api/v1/series/episodes?series_id=1"
POST/api/v1/series/episodes/add

Add an episode to a series.

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"series_id":1,"file_id":10,"file_path":"/media/series/s01e01.mp4","season_number":1,"episode_number":1,"title":"Chapter One","description":"The first chapter"}' \
  http://localhost:8080/api/v1/series/episodes/add
GET/api/v1/series/episodes/stream?id={id}

Stream an episode. Supports HTTP Range and ?tkn= query param.

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8080/api/v1/series/episodes/stream?id=101"

Music

Music tracks, streaming, and play statistics. No auth middleware on these routes.

GET/api/v1/musicPUBLIC

Get all music tracks.

curl http://localhost:8080/api/v1/music
GET/api/v1/music/get?id={id}PUBLIC

Get a single track by ID.

curl "http://localhost:8080/api/v1/music/get?id=1"
GET/api/v1/music/search?title={query}PUBLIC

Search tracks by title. Note: query param is 'title', not 'q'.

curl "http://localhost:8080/api/v1/music/search?title=bohemian"
POST/api/v1/music/add?uri={youtube_url}PUBLIC

Add a track by URI (downloads via yt-dlp). Uses form value, not JSON.

curl -X POST \
  "http://localhost:8080/api/v1/music/add?uri=https://youtube.com/watch?v=..."
PUT/api/v1/music/updatePUBLIC

Update an existing track's metadata via JSON body.

curl -X PUT \
  -d '{"id":1,"title":"Updated Title","artist":"Updated Artist","album":"Updated Album","duration":210.5,"releaseYear":2024,"filePath":"/path/to/song.mp3","ytUri":"https://youtube.com/watch?v=...","imagePath":"/path/to/cover.jpg","size":5000000,"createdAt":"2026-09-15T..."}' \
  http://localhost:8080/api/v1/music/update
GET/api/v1/music/stream?id={id}PUBLIC

Stream an audio track via http.ServeFile.

curl "http://localhost:8080/api/v1/music/stream?id=1"
POST/api/v1/music/stats/play?track_id={id}PUBLIC

Record a play event. Params via query or form values.

curl -X POST \
  "http://localhost:8080/api/v1/music/stats/play?track_id=1"
POST/api/v1/music/stats/favorite?track_id={id}&is_favorite={bool}PUBLIC

Toggle favorite status. Params via query or form values.

curl -X POST \
  "http://localhost:8080/api/v1/music/stats/favorite?track_id=1&is_favorite=true"
GET/api/v1/music/stats/play-state?track_id={id}PUBLIC

Get play state for a track.

curl "http://localhost:8080/api/v1/music/stats/play-state?track_id=1"
GET/api/v1/music/stats/play-statesPUBLIC

Get play states for all tracks.

curl http://localhost:8080/api/v1/music/stats/play-states
GET/api/v1/music/stats/is-favorite?track_id={id}PUBLIC

Check if a track is favorited.

curl "http://localhost:8080/api/v1/music/stats/is-favorite?track_id=1"
GET/api/v1/music/stats/last-playedPUBLIC

Get the last played track.

curl http://localhost:8080/api/v1/music/stats/last-played

WebSockets & Devices

GET/api/v1/devicesPUBLIC

List all currently connected WebSocket devices.

curl http://localhost:8080/api/v1/devices
GET/api/v1/ws?deviceId={id}&deviceName={name}PUBLIC

WebSocket endpoint. Connect with optional deviceId and deviceName query params.

wscat -c "ws://localhost:8080/api/v1/ws?deviceId=phone-1&deviceName=MyPhone"