Skip to content

API

Jump to bottom
scheilch edited this page Mar 8, 2026 · 1 revision

OpenCloudTouch API Reference

Overview

OpenCloudTouch exposes a RESTful API on port 7777 (default).

The API follows REST conventions and returns JSON responses. All endpoints are prefixed with /api/ except system endpoints like /health.

Interactive Documentation

When the server is running, you can access interactive API documentation:

Base URL

http://localhost:7777/api

Endpoints

Devices

List All Devices

GET /api/devices

Returns all devices currently known to the system (discovered or manually configured).

Response:

[
  {
    "device_id": "AA:BB:CC:DD:EE:FF",
    "name": "Living Room",
    "ip": "192.168.1.100",
    "type": "SoundTouch 30",
    "created_at": "2026-02-13T10:00:00Z",
    "updated_at": "2026-02-13T10:00:00Z"
  }
]

Run Device Discovery

POST /api/devices/discover

Initiates SSDP discovery for SoundTouch devices on the network.

Query Parameters:

  • timeout (optional): Discovery timeout in seconds (default: 10)

Response:

[
  {
    "device_id": "AA:BB:CC:DD:EE:FF",
    "ip": "192.168.1.100",
    "name": "Living Room",
    "type": "SoundTouch 30"
  }
]

Sync Discovered Devices

POST /api/devices/sync

Synchronizes discovered devices to the database. Typically called after /api/devices/discover.

Response:

{
  "synced_count": 3
}

Get Device Details

GET /api/devices/{device_id}

Retrieves detailed information about a specific device.

Response:

{
  "device_id": "AA:BB:CC:DD:EE:FF",
  "name": "Living Room",
  "ip": "192.168.1.100",
  "type": "SoundTouch 30",
  "firmware": "4.8.1.24047",
  "created_at": "2026-02-13T10:00:00Z",
  "updated_at": "2026-02-13T10:00:00Z"
}

Delete All Devices

DELETE /api/devices

Removes all devices from the database.

Response:

{
  "deleted_count": 3
}

Presets

Get Device Presets

GET /api/devices/{device_id}/presets

Retrieves all configured presets (slots 1-6) for a device.

Response:

[
  {
    "device_id": "AA:BB:CC:DD:EE:FF",
    "preset_number": 1,
    "station_name": "BBC Radio 1",
    "station_url": "http://stream.example.com/bbc1",
    "created_at": "2026-02-13T10:00:00Z"
  }
]

Set Preset

PUT /api/devices/{device_id}/presets/{slot}

Assigns a radio station to a preset slot (1-6).

Path Parameters:

  • device_id: Device MAC address
  • slot: Preset number (1-6)

Request Body:

{
  "station_name": "BBC Radio 1",
  "station_url": "http://stream.example.com/bbc1"
}

Response:

{
  "device_id": "AA:BB:CC:DD:EE:FF",
  "preset_number": 1,
  "station_name": "BBC Radio 1",
  "station_url": "http://stream.example.com/bbc1",
  "created_at": "2026-02-13T10:30:00Z"
}

Clear Preset

DELETE /api/devices/{device_id}/presets/{slot}

Removes a preset from the specified slot.

Response:

{
  "deleted": true
}

Radio

Search Radio Stations

GET /api/radio/search

Searches for radio stations via RadioBrowser.info API.

Query Parameters:

  • query (optional): Search term (station name)
  • country (optional): ISO country code (e.g., "GB")
  • tag (optional): Genre/tag filter (e.g., "pop")
  • limit (optional): Max results (default: 50)

Response:

[
  {
    "station_id": "uuid-12345",
    "name": "BBC Radio 1",
    "url": "http://stream.example.com/bbc1",
    "country": "GB",
    "codec": "MP3",
    "bitrate": 128,
    "tags": ["pop", "rock"],
    "favicon": "http://example.com/logo.png",
    "homepage": "http://bbc.co.uk/radio1",
    "provider": "radiobrowser"
  }
]

List Countries

GET /api/radio/countries

Returns all available countries with station counts.

Response:

[
  {
    "code": "GB",
    "name": "United Kingdom",
    "station_count": 1234
  }
]

List Genres/Tags

GET /api/radio/genres

Returns all available genre tags.

Response:

[
  {
    "name": "pop",
    "station_count": 5678
  }
]

Settings

Get Manual Device IPs

GET /api/settings/manual-ips

Retrieves the list of manually configured device IPs.

Response:

{
  "ips": ["192.168.1.100", "192.168.1.101"]
}

Update Manual Device IPs

PUT /api/settings/manual-ips

Updates the list of manual device IPs (persisted to database).

Request Body:

{
  "ips": ["192.168.1.100", "192.168.1.101", "192.168.1.102"]
}

Response:

{
  "ips": ["192.168.1.100", "192.168.1.101", "192.168.1.102"]
}

System

Health Check

GET /health

Returns server health status.

Response:

{
  "status": "healthy",
  "timestamp": "2026-02-13T10:00:00Z"
}

System Information

GET /api/system/info

Returns system metadata (version, build info).

Response:

{
  "version": "0.2.0",
  "environment": "production"
}

Error Handling

All endpoints return consistent error responses:

400 Bad Request

{
  "detail": "Invalid preset number. Must be between 1 and 6."
}

404 Not Found

{
  "detail": "Device not found: AA:BB:CC:DD:EE:FF"
}

500 Internal Server Error

{
  "detail": "Failed to connect to device"
}

CORS Configuration

By default, CORS allows requests from:

  • http://localhost:3000 (development)
  • http://localhost:5173 (Vite dev server)
  • http://localhost:7777 (production)

Configure custom origins via:

# config.yaml
cors_origins:
  - "http://truenas.local:7777"

⚠️ Security Warning: Never use ["*"] in production environments.

Authentication

None. OpenCloudTouch is designed for local network use only.

For production deployments, consider adding reverse proxy authentication (nginx, Caddy) if exposing to untrusted networks.

Rate Limiting

No rate limits applied. API is designed for single-user/household use on local network.

Versioning

API version follows application version (currently v0.2.0).

Breaking changes will increment the minor version (e.g., v0.2.x → v0.3.0).

OpenCloudTouch

🇩🇪 Benutzerhandbuch

🇬🇧 User Guide

Development

API & Architecture

Technical Reference

Legal

Clone this wiki locally