API Reference

Beam control-plane endpoints for session lifecycle and join routing.

The current Beam server exposes a minimal REST control plane so another product can mint sessions, fetch status, accept them, end them, and hand viewer flows the connection metadata they need.

Authentication

Protected session management routes use Bearer authentication:

Authorization: Bearer YOUR_BEAM_API_KEY

Public join requests use the session’s join token instead of a Bearer API key.

Endpoints

Method	Path	Description
`GET`	`/healthz`	Health check endpoint.
`POST`	`/v1/sessions`	Create a session and receive an ID, code, and join token.
`GET`	`/v1/sessions/{id}`	Fetch session status and metadata.
`POST`	`/v1/sessions/{id}/accept`	Mark the session as accepted.
`POST`	`/v1/sessions/{id}/end`	End the session.
`POST`	`/v1/join`	Exchange a join token for signaling, relay, and WebRTC metadata.

Create a session

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

{
  "purpose": "customer support",
  "ttl_seconds": 900,
  "webhook_url": "https://example.com/webhooks/beam"
}

{
  "id": "sess_01...",
  "code": "ABC-123-XYZ",
  "join_token": "join_01...",
  "expires_in": 900
}

Join a session

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

{
  "join_token": "join_01..."
}

{
  "id": "sess_01...",
  "code": "ABC-123-XYZ",
  "signaling_url": "ws://PUBLIC_HOST:8765/ws",
  "relay_host": "PUBLIC_HOST",
  "relay_udp_port": 8767,
  "rtc_url": "ws://PUBLIC_HOST:8771/rtc",
  "status": "created"
}

Session status model

created: session exists and is ready to be joined
accepted: session has been accepted and should proceed
ended: session has been closed

Health check

GET /healthz

{
  "status": "ok"
}