klangkiste/docs/api.md

Box HTTP API

Purpose

Defines the stable contract between the GUI/CLI and the Box. The Box is authoritative; the client only sends commands and reads status.

Prerequisites

• Box running on http://127.0.0.1:8000

Step-by-step

Status

curl http://127.0.0.1:8000/status

Command (example)

curl -X POST http://127.0.0.1:8000/command \
  -H "Content-Type: application/json" \
  -d '{"command":"nfc_on","payload":{"uid":"UID_1"}}'

GET /status

Response fields:

• box_id: unique device ID
• wifi_state: WIFI_UNCONFIGURED | WIFI_CONNECTING | WIFI_ONLINE | WIFI_OFFLINE
• ip_address: simulated IP (192.168.4.1 or 127.0.0.1)
• connected_ssid: connected SSID or null
• wifi_profiles_count: number of stored profiles
• spotify_status: NOT_CONFIGURED | READY
• playback_state:
  • state: IDLE | PLAYING | PAUSED
  • active_uid
  • playback_root
  • current_file
  • file_index
  • position
  • duration
  • volume
  • last_error

Example response:

{
  "box_id": "klangkiste-a9f3k7m2q8",
  "wifi_state": "WIFI_ONLINE",
  "ip_address": "127.0.0.1",
  "connected_ssid": "HomeWiFi",
  "wifi_profiles_count": 1,
  "spotify_status": "READY",
  "playback_state": {
    "state": "PLAYING",
    "active_uid": "UID_1",
    "playback_root": "media/book_1",
    "current_file": "/root/klangkiste/box/data/media/book_1/01.mp3",
    "file_index": 0,
    "position": 42,
    "duration": 180,
    "volume": 40,
    "last_error": null
  }
}

POST /command

Request body:

{
  "command": "nfc_on",
  "payload": { "uid": "UID_1" }
}

Supported commands:

• nfc_on { uid }
• nfc_off { uid }
• play_pause
• next
• prev
• volume_up
• volume_down
• vol_up (alias)
• vol_down (alias)
• stop
• trigger_error { type }
• wifi_add_profile { ssid, password, priority? }
• wifi_reset
• spotify_set_tokens { access_token, refresh_token, expires_at, account_id? }
• spotify_clear

Example: add WiFi profile

curl -X POST http://127.0.0.1:8000/command \
  -H "Content-Type: application/json" \
  -d '{"command":"wifi_add_profile","payload":{"ssid":"HomeWiFi","password":"secret","priority":10}}'

Example: set Spotify tokens

curl -X POST http://127.0.0.1:8000/command \
  -H "Content-Type: application/json" \
  -d '{"command":"spotify_set_tokens","payload":{"access_token":"a","refresh_token":"b","expires_at":123}}'

Checklist

• ✅ GET /status returns JSON
• ✅ POST /command returns { "ok": true }
• ✅ No secrets appear in /status

Troubleshooting

• 400 responses:
  • Check required fields in the payload.
• CORS errors:
  • Ensure Box API is running on the expected host/port.