Skip to main content
Use a token with read permission.

​
Authentication examples

Header-based auth: 
curl http://127.0.0.1:39031/current-track \
  -H "Authorization: Bearer velora_your_token"
Query-based auth: 
curl "http://127.0.0.1:39031/current-track?access_token=velora_your_token"

​
GET /health

Returns server health and bind details. No token required. 
{
  "ok": true,
  "status": "running",
  "port": 39031,
  "host": "127.0.0.1"
}

​
GET /current-track

Returns the current playback track snapshot. 
{
  "track": {
    "id": "track_123",
    "title": "Song Name",
    "artist": "Artist Name",
    "album": "Album Name",
    "cover_url": "https://...",
    "thumbnail_url": "https://...",
    "duration": 200000,
    "position": 54321,
    "is_playing": true
  }
}

​
GET /playback-state

Returns playback flags. 
{
  "is_playing": true,
  "shuffle": false,
  "repeat": "off"
}
repeat values are normalized to off, one, all, or on.

​
GET /playback-queue

Returns queue and playhead metadata. 
{
  "queue": [
    {
      "id": "track_123",
      "title": "Song Name",
      "artist": "Artist Name",
      "duration": 200,
      "cover_url": "https://...",
      "thumbnail_url": "https://..."
    }
  ],
  "current_index": 0,
  "current_track_id": "track_123",
  "current_track_cover_url": "https://...",
  "is_playing": true,
  "shuffle": false,
  "repeat": "off",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

​
GET /user/public

Returns a normalized public profile snapshot of the active user. 
{
  "user": {
    "id": "usr_1",
    "username": "velorauser",
    "name": "Velora User",
    "profile_image_url": "https://..."
  },
  "updated_at": "2026-01-01T00:00:00.000Z"
}