Skip to main content
All endpoints on this page require a token with write permission.
Write endpoints are POST only.

​
POST /play

Starts playback. You can provide a track_id to play a specific track. Request body: 
{
  "track_id": "track_123"
}
track_id is optional. Without it, Velora can treat the request as a resume depending on current player state. Success response: 
{
  "ok": true,
  "track_id": "track_123"
}

​
POST /pause

Pauses playback. 
{
  "ok": true
}

​
POST /next

Skips to the next track. 
{
  "ok": true
}

​
POST /previous

Skips to the previous track. 
{
  "ok": true
}

​
POST /seek

Seeks playback to a position in milliseconds. Request body: 
{
  "position": 60000
}
Rules:
  • position must be a number
  • position must be greater than or equal to 0
Invalid position response (400): 
{
  "error": "position must be a non-negative number (milliseconds)"
}
Success response: 
{
  "ok": true,
  "position": 60000
}

​
POST /toggle and POST /toggle-play

Both paths toggle play and pause. Success response: 
{
  "ok": true,
  "is_playing": false
}

​
cURL examples

curl -X POST http://127.0.0.1:39031/pause \
  -H "Authorization: Bearer velora_your_token"

curl -X POST http://127.0.0.1:39031/seek \
  -H "Authorization: Bearer velora_your_token" \
  -H "Content-Type: application/json" \
  -d '{"position": 90000}'