HomeDocsREST API Reference

REST API Reference

HTTP API for controlling Soundie from any language or tool.

Base URL

http://127.0.0.1:45289

Only accessible from localhost. Binds on app startup. All responses are JSON.

Player

GET
/api/player

Get full player state including track, position, volume, shuffle, repeat.

POST
/api/player/play

Resume playback.

POST
/api/player/pause

Pause playback.

POST
/api/player/toggle

Toggle play/pause.

POST
/api/player/next

Skip to next track in queue.

POST
/api/player/previous

Go to previous track or restart current.

POST
/api/player/seek

Seek to position. Body: { position_ms: number }

POST
/api/player/volume

Set volume 0–1. Body: { volume: number }

POST
/api/player/shuffle

Toggle shuffle. Body: { enabled: boolean }

POST
/api/player/repeat

Set repeat mode. Body: { mode: "off" | "track" | "queue" }

GET /api/player — response
json
1{
2 class="token-prop">"track": {
3 class="token-prop">"id": class="token-prop">"youtube:dQw4w9WgXcQ",
4 class="token-prop">"title": class="token-prop">"Never Gonna Give You Up",
5 class="token-prop">"artist": class="token-prop">"Rick Astley",
6 class="token-prop">"album": class="token-prop">"Whenever You Need Somebody",
7 class="token-prop">"duration_ms": class="token-number">212000,
8 class="token-prop">"artwork_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
9 class="token-prop">"source": class="token-prop">"youtube",
10 class="token-prop">"provider_id": : class="token-string">"dQw4w9WgXcQ"
11 },
12 class="token-prop">"position_ms": class="token-number">45320,
13 class="token-prop">"is_playing": class="token-keyword">true,
14 class="token-prop">"volume": class="token-number">0.85,
15 class="token-prop">"shuffle": class="token-keyword">false,
16 class="token-prop">"repeat": class="token-prop">"off",
17 class="token-prop">"queue_length": class="token-number">12,
18 class="token-prop">"queue_index": class="token-number">3
19}

Queue

GET
/api/queue

Get current queue with all tracks and current index.

POST
/api/queue/add

Add a track or playlist URL to the queue.

POST
/api/queue/insert

Insert track at specific index. Body: { url, index }

DELETE
/api/queue/:index

Remove track at index.

POST
/api/queue/clear

Clear the entire queue.

POST
/api/queue/play/:index

Jump to and play track at index.

POST
/api/queue/move

Move track from one index to another. Body: { from, to }

POST /api/queue/add — body
json
1{
2 class="token-prop">"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
3 class="token-prop">"play_immediately": class="token-keyword">false
4}
5
6// Response
7{
8 class="token-prop">"track": {
9 class="token-prop">"id": class="token-prop">"youtube:dQw4w9WgXcQ",
10 class="token-prop">"title": class="token-prop">"Never Gonna Give You Up",
11 class="token-prop">"artist": class="token-prop">"Rick Astley",
12 class="token-prop">"duration_ms": class="token-number">212000
13 },
14 class="token-prop">"queue_position": class="token-number">5
15}

Library

GET
/api/library/playlists

List all saved playlists.

POST
/api/library/playlists

Create a new playlist. Body: { name, description? }

GET
/api/library/playlists/:id

Get playlist details and tracks.

DELETE
/api/library/playlists/:id

Delete a playlist.

GET
/api/library/playlists/:id/tracks

Get all tracks in a playlist.

POST
/api/library/playlists/:id/tracks

Add a track to a playlist.

POST
/api/library/import

Import a playlist from URL.

POST
/api/library/preview

Preview a playlist URL without importing.

GET /api/library/playlists — response
json
1[
2 {
3 class="token-prop">"id": class="token-prop">"550e8400-e29b-41d4-a716-class="token-number">446655440000",
4 class="token-prop">"name": class="token-prop">"Lo-Fi Vibes",
5 class="token-prop">"description": class="token-prop">"Chill beats to study to",
6 class="token-prop">"track_count": class="token-number">42,
7 class="token-prop">"created_at": class="token-prop">"class="token-number">2025-class="token-number">01-15T14:class="token-number">32:00Z",
8 class="token-prop">"artwork_url": class="token-keyword">null
9 }
10]
POST /api/library/preview — response
json
1{
2 class="token-prop">"name": class="token-prop">"Best of Synthwave [PLAYLIST]",
3 class="token-prop">"tracks": [
4 {
5 class="token-prop">"id": class="token-prop">"youtube:abc123",
6 class="token-prop">"provider_id": class="token-prop">"abc123",
7 class="token-prop">"title": class="token-prop">"Midnight Protocol",
8 class="token-prop">"artist": class="token-prop">"Cyber Dreams",
9 class="token-prop">"duration_ms": class="token-number">245000,
10 class="token-prop">"artwork_url": "https://..."
11 }
12 ]
13}

System

GET
/api/system

Get app version, platform, and status.

GET
/api/system/theme

Get the active theme definition.

POST
/api/system/theme

Set active theme by ID.

GET
/api/system/plugins

List installed plugins and their state.

GET /api/system — response
json
1{
2 class="token-prop">"version": class="token-prop">"class="token-number">0.1.class="token-number">0",
3 class="token-prop">"platform": class="token-prop">"windows",
4 class="token-prop">"arch": class="token-prop">"x86_64",
5 class="token-prop">"api_version": class="token-number">1,
6 class="token-prop">"uptime_seconds": class="token-number">3842,
7 class="token-prop">"rpc_port": class="token-number">45289
8}