HTTP API Overview

Monibuca V6 provides APIs through a built-in shared HTTP server. All plugin HTTP endpoints are registered on the same server and differentiated by route prefixes.

Server Address

The default listening address is :8180, which can be changed via configuration:

http:
  listen: ":8180"
  cors: true

HTTPS Configuration

Monibuca has built-in TLS support. You can configure HTTPS listening under global.http.

Configuration Fields

Field	Type	Description
listenaddrtls	string	HTTPS listening address, e.g., ":8443"
certfile	string	TLS certificate file path (PEM format), e.g., "/etc/ssl/fullchain.pem"
keyfile	string	TLS private key file path (PEM format), e.g., "/etc/ssl/privkey.pem"

Development: Self-Signed Certificate

For development and testing, leave certfile and keyfile empty — Monibuca will automatically generate a self-signed certificate:

global:
  http:
    listenaddr: ":8180"
    listenaddrtls: ":8443"
    # certfile: ""  # Leave empty for auto-generated self-signed cert
    # keyfile: ""

Your browser will show a certificate warning. Click “Advanced” → “Proceed” to continue.

Production: CA-Signed Certificate

Use a certificate issued by Let’s Encrypt or another CA:

global:
  http:
    listenaddr: ":8180"
    listenaddrtls: ":8443"
    certfile: "/etc/letsencrypt/live/your-domain.com/fullchain.pem"
    keyfile: "/etc/letsencrypt/live/your-domain.com/privkey.pem"

FAQ

Q: Can I enable HTTPS only and disable HTTP?

Yes, leave listenaddr empty:

global:
  http:
    listenaddr: ""            # Disable HTTP
    listenaddrtls: ":8443"
    certfile: "/etc/ssl/fullchain.pem"
    keyfile: "/etc/ssl/privkey.pem"

Q: Do I need to restart after changing HTTPS settings?

Yes. Changes to listenaddrtls and certificate paths require a restart to take effect.

Route Prefix Categories

All APIs are organized by functional modules with different route prefixes:

Core API

Prefix	Module	Description
/v6/api/	Engine Core	REST streams/aliases/tasks/proxies/system
/config/	Config framework	Read/write, schema, HTML pages
/api/config/	Runtime config	DB persistence and reload

Protocol API

Prefix	Plugin	Description
/rtmp/	RTMP	RTMP connection management
/rtsp/	RTSP	RTSP session management
/flv/	HTTP-FLV	FLV streaming endpoint
/hls/	HLS	HLS playlist and segments
/webrtc/	WebRTC	WHIP/WHEP signaling endpoint
/srt/	SRT	SRT connection management
/webtransport/	WebTransport	WebTransport sessions
/gb28181/	GB28181	Device management and control

Utility API

Prefix	Plugin	Description
/mp4/	MP4 Recording	Recording control and VOD
/snap/	Snapshot Service	Snapshots and MJPEG
/transcode/api/	Audio Transcoding	Transcoding task management
/cluster/	Cluster	Cluster status and node management

Room API

Prefix	Service/Plugin	Description
/room/	Room Service	Room management
/room_report/	Room Reporting	Room statistics data
/live/	Live Plugin	Live room management
/meeting/api/	Meeting Plugin	Meeting room REST (rooms, reservations, templates, …)

High-Frequency Endpoint Quick Reference

Default base URL: http://localhost:8180

Core and Config

• GET /v6/api/streams: Paginated stream list
• GET /v6/api/system/info: System information
• GET /v6/api/plugins: Plugin list
• GET /config/: Registered config plugins
• PUT /config/{plugin}: Update plugin config (not /config/plugin/...)

Business Plugins

• GET /live/rooms: Live room list
• POST /live/rooms: Create live room
• GET /meeting/api/rooms: Meeting room list
• POST /meeting/api/rooms: Create meeting room
• GET /customer-service/sessions: Customer service session list

Protocol and Utility

• GET /gb28181/api/devices: GB28181 device list
• POST /transcode/api/launch: Launch transcode
• GET /mp4/list: Recording list
• GET /snap/api/{streamPath}: Snapshot (preferred; legacy GET /snap/take/{streamPath} also works)
• POST /webrtc/push/{streamPath}: WHIP publish

Meeting REST

This section documents the Meeting plugin HTTP API and is kept in sync with section 14.2 Meeting in the repository root docs/http-api.md. When routes change, update both places so this page and the repo-side doc stay aligned.

Like other plugins, Meeting REST is mounted under {plugin}/api, i.e. /meeting/api. After the engine registers the meeting/api prefix, the handler sees sub-paths such as /rooms, /reservations, etc. (same pattern as gb28181/api, /users/api, …).

Route prefix

Prefix	Purpose	Handler
/meeting/api	Meeting room REST	MeetingApiHandler

Full paths (client requests)

Method	Path	Description
GET	/meeting/api/rooms	List meeting rooms
POST	/meeting/api/rooms	Create room (JSON body: room_id)
GET	/meeting/api/rooms/{room_id}	Room summary; legacy alias GET /meeting/api/room/{room_id}
DELETE	/meeting/api/rooms/{room_id}	Delete room
GET	/meeting/api/rooms/{room_id}/users	Users in room
POST	/meeting/api/rooms/{room_id}/lock	Lock room
POST	/meeting/api/rooms/{room_id}/unlock	Unlock room
POST	/meeting/api/control/mute	Chat mute (JSON: room_id, user_id)
POST	/meeting/api/control/unmute	Remove chat mute
POST	/meeting/api/control/kick	Remove user from room
GET	/meeting/api/stats	Meeting statistics
GET	/meeting/api/features	Registered feature metadata
GET	/meeting/api/reservations	List reservations
POST	/meeting/api/reservations	Create reservation
GET	/meeting/api/templates	List templates
POST	/meeting/api/templates	Create template
PUT	/meeting/api/templates/{id}	Update template
DELETE	/meeting/api/templates/{id}	Delete template
GET	/meeting/api/recordings	Recording catalog (may be empty until persistence is wired)
GET	/meeting/api/recordings/{id}/play	Play URL (404 if not found)
GET	/meeting/api/recordings/{id}/download	Download
DELETE	/meeting/api/recordings/{id}	Delete recording

Note: Agenda, transcription, and in-session control are primarily WebSocket (/room/{room_id}?type=meeting). Do not use the legacy /room/meeting/... prefix for Meeting REST. For concepts and signaling, see the Meeting Room plugin page.

Common Request Conventions

Request Format

• Content-Type: application/json (for POST/PUT requests)
• Character encoding: UTF-8
• URL encoding: URL-encode streamPath when it contains / (e.g. live%2Fdemo)

Response Format

/v6/api/ — success returns resource JSON or { "data", "meta" }; failures use RFC 7807 Problem Detail.

/config/ — { code, message, data } envelope.

HTTP Status Codes

Status Code	Description
200	Request successful
400	Invalid request parameters
401	Unauthorized (authentication required)
403	Forbidden
404	Resource not found
500	Internal server error
501	Not implemented
503	Service unavailable

Authentication

Monibuca V6 supports API authentication via JWT (JSON Web Token).

Enable Authentication

auth:
  enabled: true
  secret: "your-jwt-secret-key"
  expire: 86400              # Token validity period (seconds)
  exclude:                   # Paths exempt from authentication
    - "/api/login"
    - "/flv/"
    - "/hls/"

Obtain Token

POST /api/login
Content-Type: application/json

{
  "username": "admin",
  "password": "password"
}

Response:

{
  "code": 0,
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Use Token

Include the token in subsequent request headers:

GET /v6/api/streams
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Auth Secret API

Generates stream auth signatures (secret + expire):

GET /v6/api/streams/secret?stream_path={streamPath}&type={publish|subscribe}&expire=<hex>&plugin=<pluginName>

• stream_path: stream path
• type: publish or subscribe, default publish
• expire: optional hex Unix timestamp; defaults to now + 30 minutes
• plugin: optional plugin name; default global

Response example:

{
  "secret_type": "publish",
  "plugin": "rtmp",
  "stream_path": "live/test",
  "expire": "6610f4a0",
  "secret": "0123456789abcdef0123456789abcdef"
}

CORS Support

CORS is enabled by default, allowing cross-origin access. It can be configured:

http:
  cors: true
  cors_origins:
    - "http://localhost:3000"
    - "https://your-domain.com"

API Documentation Navigation

• Component API Overview — Route prefixes and common endpoint entries by component
• Meeting REST — Full Meeting plugin route table (aligned with docs/http-api.md §14.2)
• Stream Management API — Stream listing, details, and control
• Configuration Management API — Configuration read/write and hot reload
• GB28181 Protocol Plugin — protocol capabilities and embedded API guide
• Advanced: Stream Authentication — algorithm, custom handler, and signing endpoint