API Reference

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

Beam exposes a small REST control plane so another product or internal tool can create sessions, fetch their state, accept them, end them, and deliver the join metadata a viewer flow needs.

Authentication

Protected session-management routes use Bearer authentication:

Authorization: Bearer YOUR_BEAM_API_KEY

Public join requests use the session 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"
}