Beam

API Reference

Beam control-plane endpoints for typed sessions and join routing.

Beam exposes a small REST control plane so another product, admin tool, support portal, or game launcher can create screenshare or stream sessions, fetch their state, accept them, end them, and deliver join metadata to viewers.

Authentication

Session-management routes accept either a workspace API key or a dashboard bearer token:

Authorization: Bearer YOUR_BEAM_API_KEY
Authorization: Bearer bt_dashboard_user_token

Public join requests use the session join token instead of a Bearer API key. Accept requests can be authorized either by API key or the join token.

Endpoints

Method Path Description
GET /healthz Health check endpoint.
GET /v1/capabilities Lists supported session modes, stream profiles, viewer protocols, and recommended defaults.
POST /v1/auth/register Create a SaaS user, workspace, owner membership, dashboard token, and default API key.
POST /v1/auth/login Issue a dashboard bearer token for an existing user.
GET /v1/me Return current user, workspace, role, and API keys.
POST /v1/sessions Create a typed session and receive an ID, code, join token, and recommended settings.
POST /v1/streams Create a public or private stream session owned by the workspace.
GET /v1/streams List workspace streams for the authenticated user or API key.
GET /v1/streams/public List public stream metadata for the public stream directory.
GET /v1/media/edge Return WHIP, WHEP, HLS, LL-HLS, SFU, and simulcast media-edge capabilities.
GET /v1/streams/{id}/media Return the stream media path plus playback URLs. Authorized callers also receive the WHIP ingest URL.
POST /v1/streams/{id}/sources Add screen, window, camera, microphone, game, or external source metadata.
POST /v1/streams/{id}/layout Set single, horizontal, vertical, grid, or focus layout metadata.
WS /v1/streams/realtime WebSocket signaling for browser publishers and viewers using Beam stream join tokens.
GET /v1/sessions/{id} Fetch session status and metadata.
POST /v1/sessions/{id}/accept Mark the session as accepted using either the owner API key or the join token.
POST /v1/sessions/{id}/end End the session.
POST /v1/join Exchange a join token for signaling, relay, WebRTC, and stream-profile metadata.

Capabilities

GET /v1/capabilities
{
  "session_modes": ["screenshare", "stream"],
  "stream_profiles": ["balanced", "crisp", "low_latency", "gaming"],
  "viewer_protocols": ["native-relay", "browser-webrtc", "webrtc-whep", "hls", "ll-hls"],
  "features": [
    "typed-sessions",
    "relay-routing",
    "browser-viewer",
    "system-audio",
    "adaptive-bitrate",
    "webhooks",
    "whip-ingest-ready",
    "webrtc-whep-playback-ready",
    "hls-ll-hls-output-ready"
  ],
  "default_screen_share": {
    "target_fps": 30,
    "bitrate_kbps": 12000,
    "audio_enabled": true,
    "latency_profile": "balanced",
    "capture_profile": "desktop",
    "recommended_use": "Remote support, onboarding, and guided screen sharing."
  }
}

Media edge

Use these endpoints when a stream needs scalable playback or a slow-network fallback beyond the direct Beam browser WebRTC path.

GET /v1/media/edge
GET /v1/streams/{id}/media?join_token=jt_xxx
{
  "stream_id": "sess_xxx",
  "media_path": "beam-sess_xxx",
  "enabled": true,
  "provider": "mediamtx",
  "whip_url": "https://beam.be-online.ro/whip/beam-sess_xxx/whip",
  "whep_url": "https://beam.be-online.ro/whep/beam-sess_xxx/whep",
  "hls_url": "https://beam.be-online.ro/hls/beam-sess_xxx/index.m3u8",
  "latency_profiles": ["interactive-webrtc", "low-latency-hls", "stable-hls"]
}

Public callers receive playback URLs. The WHIP ingest URL is returned only to a valid dashboard/API principal or a valid stream join token.

Create a screenshare session

POST /v1/sessions
Authorization: Bearer YOUR_BEAM_API_KEY
Content-Type: application/json

{
  "mode": "screenshare",
  "stream_profile": "balanced",
  "audio_enabled": true,
  "purpose": "customer support",
  "customer": "acct_2048",
  "ttl_seconds": 900,
  "webhook_url": "https://example.com/webhooks/beam",
  "metadata": {
    "ticket_id": "SUP-921",
    "agent_id": "ops-14"
  }
}
{
  "id": "sess_01...",
  "code": "ABC-123-XYZ",
  "join_token": "jt_01...",
  "mode": "screenshare",
  "stream_profile": "balanced",
  "audio_enabled": true,
  "expires_in": 900,
  "viewer_protocols": ["native-relay", "browser-webrtc"],
  "recommended_settings": {
    "target_fps": 30,
    "bitrate_kbps": 12000,
    "audio_enabled": true,
    "latency_profile": "balanced",
    "capture_profile": "desktop",
    "recommended_use": "Remote support, onboarding, and guided screen sharing."
  }
}

Create a stream session

POST /v1/sessions
Authorization: Bearer YOUR_BEAM_API_KEY
Content-Type: application/json

{
  "mode": "stream",
  "stream_profile": "gaming",
  "audio_enabled": true,
  "purpose": "launch-day stream",
  "customer": "creator_991",
  "metadata": {
    "game_slug": "space-raiders",
    "campaign": "summer-release"
  }
}

Join a session

POST /v1/join
Content-Type: application/json

{
  "join_token": "jt_01..."
}
{
  "id": "sess_01...",
  "code": "ABC-123-XYZ",
  "status": "created",
  "mode": "stream",
  "stream_profile": "gaming",
  "audio_enabled": true,
  "signaling_url": "ws://PUBLIC_HOST:8765/ws",
  "relay_host": "PUBLIC_HOST",
  "relay_udp_port": 8767,
  "rtc_url": "ws://PUBLIC_HOST:8771/rtc",
  "viewer_protocols": ["native-relay", "browser-webrtc"],
  "features": [
    "relay-routing",
    "browser-viewer",
    "system-audio",
    "adaptive-bitrate",
    "low-latency",
    "webhooks"
  ],
  "recommended_settings": {
    "target_fps": 60,
    "bitrate_kbps": 18000,
    "audio_enabled": true,
    "latency_profile": "interactive",
    "capture_profile": "game-or-app",
    "recommended_use": "Fast-moving gameplay, creative tools, and live product walkthroughs."
  }
}

Accept a session

POST /v1/sessions/sess_01.../accept
Content-Type: application/json

{
  "join_token": "jt_01..."
}

This route returns 409 invalid_state if the session is already ended or expired.

Session status model

  • created: session exists and is ready to be joined.
  • accepted: the operator or customer flow has confirmed the session should proceed.
  • ended: the session was closed intentionally.
  • expired: the session aged out before completion.

Webhook payload

{
  "type": "session.created",
  "session_id": "sess_01...",
  "code": "ABC-123-XYZ",
  "status": "created",
  "mode": "stream",
  "stream_profile": "gaming",
  "audio_enabled": true,
  "customer": "creator_991",
  "purpose": "launch-day stream",
  "metadata": {
    "game_slug": "space-raiders"
  },
  "sent_at": 1780806400
}