GET /api/machine-live — live video stream endpoints

These two endpoints manage the live video stream URL for each machine. Operators and admins can retrieve the current stream URL to embed in the dashboard. Raspberry Pi boot scripts use the update endpoint to publish the active tunnel URL whenever the device restarts.

The GET endpoint uses Bearer token authentication (operator or admin role). The POST endpoint uses a separate shared secret passed via the X-Live-Update-Token header, intended for machine-side automation rather than user sessions.

GET /api/machine-live/

Returns the configured live stream URL for a machine. When a URL has been saved to the database, it takes priority over any static URL set via environment variable.

Path parameters

machine_id

string

required

The machine identifier (e.g., cnc, plc, melfa). Normalized to lowercase.

Headers

Authorization

string

required

Bearer token for an operator or admin account. Example: Bearer <token>.

Response

machine_id

string

required

Normalized machine identifier.

machine_name

string

required

Human-readable display name (e.g., "CNC").

is_configured

boolean

required

true when a stream URL is available. false when no URL has been set in the database or environment.

stream_url

string

The active stream URL, or null when is_configured is false.

curl --request GET \
  --url https://your-host/api/machine-live/cnc \
  --header "Authorization: Bearer <token>"

200 — stream configured

{
  "machine_id": "cnc",
  "machine_name": "CNC",
  "is_configured": true,
  "stream_url": "https://abc123.trycloudflare.com/stream"
}

200 — not configured

{
  "machine_id": "cnc",
  "machine_name": "CNC",
  "is_configured": false,
  "stream_url": null
}

404

{
  "error": "Unknown machine selected."
}

POST /api/machine-live//url

Updates the live stream URL for a machine. This endpoint is called by the Raspberry Pi boot script after establishing a Cloudflare tunnel, registering the new public URL so the dashboard reflects the active stream.

Path parameters

machine_id

string

required

The machine identifier (e.g., cnc, plc, melfa).

Headers

X-Live-Update-Token

string

required

Shared secret token. Must match the MACHINE_LIVE_UPDATE_TOKEN environment variable configured on the server. This is a machine-to-server token and is separate from user Bearer tokens.

Body

stream_url

string

required

The new stream URL to register. Must be a valid http or https URL.

source

string

default:"raspberry_pi"

Optional label identifying the source of the update (e.g., "raspberry_pi").

Response

message

string

required

Confirmation message: "Live stream URL updated successfully."

machine_id

string

required

Normalized machine identifier.

machine_name

string

required

Human-readable display name.

stream

object

required

The saved stream record as persisted in the database.

Show properties

stream_url

string

The stored stream URL.

source

string

Source label as provided in the request body.

If MACHINE_LIVE_UPDATE_TOKEN is not set on the server, all requests to this endpoint return 503. Configure the environment variable before deploying the Raspberry Pi script.

curl --request POST \
  --url https://your-host/api/machine-live/cnc/url \
  --header "Content-Type: application/json" \
  --header "X-Live-Update-Token: <update-token>" \
  --data '{
    "stream_url": "https://abc123.trycloudflare.com/stream",
    "source": "raspberry_pi"
  }'

200

{
  "message": "Live stream URL updated successfully.",
  "machine_id": "cnc",
  "machine_name": "CNC",
  "stream": {
    "stream_url": "https://abc123.trycloudflare.com/stream",
    "source": "raspberry_pi"
  }
}

401

{
  "error": "Invalid live stream update token."
}

400

{
  "error": "A valid http or https stream_url is required."
}

503

{
  "error": "Live stream update token is not configured."
}

Authentication

Chat

Machine Monitoring

Admin

GET /api/machine-live — live video stream endpoints