Remote Control API

This page is the protocol-level reference. For setup, examples, and controller-specific tips, see Remote control.

Command catalog

Twelve commands are supported by both protocols:

Commands are case-insensitive on input. value argument types vary: theme is a string, opacity and confidence are floats in [0.0, 1.0], and on_air is a boolean (true / false).

next, prev, bible_next, bible_prev, send_to_live, add_to_queue, show and hide take no argument.

Over OSC an extra argument is ignored, so a controller that sends a value with every button press works unchanged. Over HTTP the body must match exactly — adding a value key to an argument-free command returns 422.

bible_next and bible_prev step within the current chapter and continue into the adjacent chapter of the same book at its edges. They stop at a book boundary rather than rolling into the next book, and do nothing at all when there is no chapter on the other side.

send_to_live and add_to_queue act on the verse in Program preview. With nothing previewed, both are no-ops — send_to_live will never blank the live output.

OSC

OSC runs over UDP on port 8000 (configurable). Address pattern is /rhema/<command>. Type coercion is permissive — int, float, and bool argument types are coerced to the target command variant without error, so any controller's idea of how to send a number works.

HTTP API

The HTTP server is built with Axum, listens on port 8080 (configurable), and exposes three endpoints under the /api/v1/ prefix.

GET /api/v1/health

A liveness check that returns the service identity:

curl http://localhost:8080/api/v1/health

{ "status": "ok", "service": "rhema", "version": "..." }

GET /api/v1/status

curl http://localhost:8080/api/v1/status

Returns a state snapshot from a Rust-side cache that the frontend refreshes once per second:

{
  "on_air": true,
  "active_theme": "Classic Dark",
  "live_verse": "John 3:16",
  "queue_length": 12,
  "confidence_threshold": 0.75
}

active_theme and live_verse are nullable — they're null until a theme is selected or a verse is sent live.

POST /api/v1/command

Dispatch any command from the catalog. The body is JSON with a command key and (for commands that take a parameter) a value key:

curl -X POST http://localhost:8080/api/v1/command \
  -H 'Content-Type: application/json' \
  -d '{"command":"theme","value":"Classic Dark"}'

{ "success": true }

error is present only on failure. Unknown commands and invalid JSON are rejected with success: false and a descriptive error string.

POST /api/v1/control is mounted as an alias for the same handler. Earlier builds mounted only that path while the docs advertised /api/v1/command, so the alias stays to keep existing integrations working. Write new ones against /api/v1/command.

Persistence and shutdown semantics

Both listeners can be started and stopped at runtime without restarting Rhema. Port-bind failures surface as visible errors in the Settings panel rather than silent listener crashes. Both listeners shut down cleanly on app exit — no zombie threads, no orphaned ports.

Authentication

By default both protocols are unauthenticated and bind to 0.0.0.0. For multi-machine deployments, route them through your network's existing auth (a reverse proxy with mTLS, a Tailscale ACL, etc.) — the API is intentionally simple and protocol-only so it composes with whatever you already trust. For local-only access, bind to 127.0.0.1 in Settings → Remote.

Status field reference

The keys returned by /api/v1/status: