API Reference

This document details all HTTP API endpoints of live-webrtc-go.

Table of Contents

  1. API Reference
    1. Authentication
      1. 1. Bearer Token
      2. 2. X-Auth-Token Header
      3. Authentication Priority
    2. Streaming Endpoints
      1. WHIP Publish
      2. WHEP Play
    3. Query Endpoints
      1. Get Bootstrap Configuration
      2. Get Room List
      3. Get Recording List
    4. Admin Endpoints
      1. Close Room
    5. Health and Metrics
      1. Health Check
      2. Prometheus Metrics
    6. Error Responses
      1. Common Error Codes
    7. CORS Configuration
    8. Request Limits
    9. Room Name Rules

Authentication

The system supports two authentication methods, tried in order of priority:

1. Bearer Token

1

Authorization: Bearer <token>

2. X-Auth-Token Header

1

X-Auth-Token: <token>

Authentication Priority

  1. Room-level Token (ROOM_TOKENS)
  2. Global Token (AUTH_TOKEN)
  3. JWT (JWT_SECRET)
  4. No authentication (when not configured)

Streaming Endpoints

WHIP Publish

Publish media stream to a specified room.

1
2
3

POST /api/whip/publish/{room}
Content-Type: application/sdp
Authorization: Bearer <token>

Parameters

Parameter Location Type Required Description
room path string Yes Room name, matches ^[A-Za-z0-9_-]{1,64}$

Request Body

SDP Offer (text/plain)

Response

Status Code Description
201 Success, returns SDP Answer
400 Invalid SDP or room name
401 Authentication failed
409 Room already has a publisher
429 Rate limit exceeded

Example

1
2
3
4

curl -X POST "http://localhost:8080/api/whip/publish/demo" \
  -H "Content-Type: application/sdp" \
  -H "Authorization: Bearer mytoken" \
  --data-binary @offer.sdp

WHEP Play

Subscribe to media stream from a specified room.

1
2
3

POST /api/whep/play/{room}
Content-Type: application/sdp
Authorization: Bearer <token>

Parameters

Parameter Location Type Required Description
room path string Yes Room name

Request Body

SDP Offer (text/plain)

Response

Status Code Description
201 Success, returns SDP Answer
400 Invalid SDP or room name
401 Authentication failed
403 Subscriber limit reached (MAX_SUBS_PER_ROOM)
404 No active publisher in room
429 Rate limit exceeded

Example

1
2
3
4

curl -X POST "http://localhost:8080/api/whep/play/demo" \
  -H "Content-Type: application/sdp" \
  -H "Authorization: Bearer mytoken" \
  --data-binary @offer.sdp

Query Endpoints

Get Bootstrap Configuration

Returns runtime configuration required by the frontend application.

1

GET /api/bootstrap

Response

1
2
3
4
5
6
7
8
9
10
11
12
13

{
  "authEnabled": true,
  "recordEnabled": true,
  "iceServers": [
    {
      "urls": ["stun:stun.l.google.com:19302"]
    }
  ],
  "features": {
    "rooms": true,
    "records": true
  }
}

Field Descriptions

Field Type Description
authEnabled boolean Whether authentication is enabled
recordEnabled boolean Whether recording is enabled
iceServers array ICE server configuration
features object Feature flags

Get Room List

Returns all active rooms and their status.

1

GET /api/rooms

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14

[
  {
    "name": "demo",
    "hasPublisher": true,
    "tracks": 2,
    "subscribers": 5
  },
  {
    "name": "test",
    "hasPublisher": false,
    "tracks": 0,
    "subscribers": 0
  }
]

Field Descriptions

Field Type Description
name string Room name
hasPublisher boolean Whether room has a publisher
tracks number Number of active media tracks
subscribers number Number of active subscriber connections

Get Recording List

Returns metadata for all recording files.

1

GET /api/records

Response

1
2
3
4
5
6
7
8

[
  {
    "name": "demo_video0_1710123456.ivf",
    "size": 1048576,
    "modTime": "2024-03-10T12:34:56Z",
    "url": "/records/demo_video0_1710123456.ivf"
  }
]

Field Descriptions

Field Type Description
name string File name
size number File size in bytes
modTime string Modification time (ISO 8601 / RFC 3339 UTC)
url string Relative URL to download the recording

Admin Endpoints

Close Room

Forcefully close a specified room, disconnecting all connections.

1
2

POST /api/admin/rooms/{room}/close
Authorization: Bearer <admin-token>

Parameters

Parameter Location Type Required Description
room path string Yes Room name to close

Response

Status Code Description
200 Successfully closed
401 Authentication failed (requires Admin Token)
404 Room not found

Example

1
2
3

curl -X POST \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  http://localhost:8080/api/admin/rooms/demo/close

Health and Metrics

Health Check

1

GET /healthz

Response

1

ok

Status code: 200

Prometheus Metrics

1

GET /metrics

Available Metrics

Metric Name Type Labels Description
live_rooms Gauge - Active room count
live_subscribers GaugeVec room Subscribers per room
live_rtp_bytes_total CounterVec room Total RTP bytes
live_rtp_packets_total CounterVec room Total RTP packets

Example

1

curl http://localhost:8080/metrics

Error Responses

Domain-specific WHIP/WHEP errors use this JSON format:

1
2
3

{
  "error": "Error description"
}

Generic HTTP errors produced by shared validation, auth, body-size, method, or rate-limit checks may still be returned as plain text.

Common Error Codes

Status Code Error Message Reason
400 invalid room name Invalid room name format
400 invalid SDP Invalid SDP format
401 unauthorized Authentication failed or not provided
403 subscriber limit reached MAX_SUBS_PER_ROOM limit hit (WHEP)
404 no active publisher in room No publisher in room (WHEP play)
409 publisher already exists in this room Room already has a publisher (WHIP)
429 too many requests Rate limit triggered
500 internal server error Internal server error

CORS Configuration

All API responses include CORS headers:

1
2
3

Access-Control-Allow-Origin: <ALLOWED_ORIGIN>
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization, X-Auth-Token

Preflight requests (OPTIONS) automatically return 204.

Request Limits

Limit Value Configuration
SDP request body size 1 MB Hardcoded
Room name length 1-64 characters Regex ^[A-Za-z0-9_-]{1,64}$
Request rate Configurable RATE_LIMIT_RPS, RATE_LIMIT_BURST
Subscribers per room Configurable MAX_SUBS_PER_ROOM

Room Name Rules

  • Allowed characters: A-Z, a-z, 0-9, _, -
  • Maximum length: 64 characters
  • Pattern: ^[A-Za-z0-9_-]{1,64}$

Valid examples: room1, my-room, live_stream_01

Invalid examples: my room, room@123, a (too short if min>1)