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
/api/	V5 compat (legacy envelope)	V5CompatSurface
/v6/api/	Engine Core	REST streams/aliases/tasks/proxies/system
/zego/api/	ZEGO Action API (feature)	ZegoCompatSurface
/config/	Config framework	Read/write, schema, HTML pages
/api/config/	Runtime config	DB persistence and reload

Dual management API surfaces

Monibuca V6 exposes two HTTP management surfaces that share the same AppFacade application layer:

Surface	Prefix	Response format	Use case
V5 compat	/api/*	{ code, message, data } legacy envelope	Admin UI, scripts and integrations migrated from v5
V6 native	/v6/api/*	Resource JSON / RFC 7807 Problem Detail	New integrations, RESTful clients

• URLs unchanged: Integrations migrated from v5 keep using /api/... paths — no URL changes required.
• Same auth: When global.auth.secret is set, sensitive GETs and all writes on both surfaces require an admin JWT (Authorization: Bearer …); login at /api/auth/login (see Authentication below).
• Feature gaps: Stop/change subscriber by ID (/api/subscriber/stop/{id}) is only on /api/*; /v6/api/* focuses on REST resources. New capabilities are added to the V6 surface first.

Representative V5 compat paths (full list in repo docs/http-api.md):

Category	Examples
System	GET /api/summary, GET /api/sysinfo, GET /api/plugins
Streams	GET /api/stream/list, GET /api/stream/info/{path}, POST /api/stream/stop/{path}
Proxies	GET /api/proxy/pull/list, POST /api/pull-proxy/add, POST /api/pull-proxy/start/{id}
Recordings	GET /api/record/list, DELETE /api/record/delete
Config	GET /api/config/file, POST /api/config/modify, GET /api/config/get/{name}
Tasks	GET /api/task/tree, POST /api/task/stop/{id}

ZEGO compat (requires api-compat-zego feature): Action-style API at POST /zego/api/?Action=DescribeStreamList with MD5 signature auth. Implemented actions include DescribeStreamList, DescribeStreamInfo, ForbidRTCStream, DescribeUserNum, and others.

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 /api/summary: System summary (V5 compat envelope)
• GET /api/stream/list: Stream list (V5 compat envelope)
• GET /v6/api/streams: Paginated stream list (V6 REST)
• GET /v6/api/system/info: System information
• GET /api/plugins or 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

/api/ (V5 compat) — { "code", "message", "data" } legacy envelope; code: 0 means success. The Admin UI and v5-migrated scripts depend on this shape.

/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 uses JWT for the management plane. Stream publish/play URL auth (secret/expire) is separate — see Auth Secret API below.

Enable management API auth

global:
  auth:
    secret: "your-jwt-secret-key"
    users:
      - username: admin
        password: your_secure_password
        role: admin

Or set M7S_AUTH_SECRET. Without an explicit secret, an ephemeral JWT secret is used (tokens are not stable across restarts); the admin gate stays enabled.

For local dev only: M7S_ADMIN_DEV_MODE=1.

Login and refresh

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

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

Response (legacy envelope):

{
  "code": 0,
  "message": "success",
  "data": {
    "access_token": "eyJ…",
    "refresh_token": "eyJ…",
    "expires_in": 86400,
    "token_type": "Bearer",
    "username": "admin",
    "role": "admin"
  }
}

POST /api/auth/refresh
Content-Type: application/json

{ "refresh_token": "eyJ…" }

GET /api/auth/userinfo
Authorization: Bearer eyJ…

Use token

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

Sensitive GETs on built-in /api/* and all mutations require the admin role (or M7S_ADMIN_DEV_MODE=1).

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