Configuration Management API

Monibuca V6 provides a complete configuration management API, supporting runtime configuration reading and modification, schema queries, configuration value validation, and real-time notifications of configuration changes via WebSocket.

Get Global Configuration

GET /config/global

Returns the engine’s global configuration.

Response example:

{
  "code": 0,
  "message": "success",
  "data": {
    "http": {
      "listen": ":8080",
      "cors": true
    },
    "log": {
      "level": "info",
      "file": "./logs/monibuca.log"
    },
    "publish": {
      "kick": false,
      "delay_close": 0
    },
    "subscribe": {
      "sub_audio": true,
      "sub_video": true,
      "idr_mode": 1
    }
  }
}

Get Plugin Configuration

GET /config/plugin/{plugin_name}

Returns the current configuration for the specified plugin.

Request example:

curl http://localhost:8080/config/plugin/mp4

Response example:

{
  "code": 0,
  "message": "success",
  "data": {
    "enable": true,
    "record_path": "./recordings",
    "fragment": false,
    "fragment_duration": 5,
    "max_file_size": 0,
    "max_duration": 0,
    "expire_days": 0,
    "auto_recovery": true,
    "filename_pattern": "{stream}_{date}_{time}.mp4"
  }
}

Update Global Configuration

PUT /config/global
Content-Type: application/json

{
  "log": {
    "level": "debug"
  }
}

Partially update the global configuration — only the fields to be modified need to be provided. Changes take effect immediately.

Response example:

{
  "code": 0,
  "message": "success",
  "data": {
    "updated_fields": ["log.level"],
    "restart_required": false
  }
}

Update Plugin Configuration

PUT /config/plugin/{plugin_name}
Content-Type: application/json

{
  "record_path": "/data/recordings",
  "expire_days": 30
}

Partially update the specified plugin’s configuration. The update triggers the plugin’s on_config_update() callback.

Response example:

{
  "code": 0,
  "message": "success",
  "data": {
    "plugin": "mp4",
    "updated_fields": ["record_path", "expire_days"]
  }
}

Schema Query

Get All Schemas

GET /config/schema

Returns JSON Schema definitions for all configurations, including global configuration and all plugin configurations. Schemas are automatically generated by the ConfigSchema derive macro.

Get Plugin Schema

GET /config/schema/{plugin_name}

Returns the configuration schema for the specified plugin.

Request example:

curl http://localhost:8080/config/schema/mp4

Response example:

{
  "code": 0,
  "message": "success",
  "data": {
    "plugin": "mp4",
    "title": "MP4 Plugin",
    "description": "MP4 recording and playback plugin",
    "type": "object",
    "properties": {
      "enable": {
        "type": "boolean",
        "label": "Enable",
        "description": "Enable the plugin",
        "default": true
      },
      "record_path": {
        "type": "string",
        "label": "Record Path",
        "description": "Recording directory path",
        "default": "./recordings"
      },
      "fragment": {
        "type": "boolean",
        "label": "Fragment",
        "description": "Enable fragmented MP4 (fMP4)",
        "default": false
      },
      "filename_pattern": {
        "type": "string",
        "label": "Filename Pattern",
        "description": "File naming pattern. Supports: {stream}, {date}, {time}, {timestamp}",
        "pattern": "^[a-zA-Z0-9_{}\\-\\.]+$",
        "default": "{stream}_{date}_{time}.mp4"
      }
    },
    "override_groups": ["Publish", "Subscribe"]
  }
}

Schema definitions can be used directly for automatic frontend form generation.

Configuration Validation

POST /config/validate/{plugin_name}
Content-Type: application/json

{
  "record_path": "/data/recordings",
  "expire_days": -1
}

Validate whether configuration values are valid without actually writing them. Returns validation results and error details.

Validation failure response:

{
  "code": 400,
  "message": "validation_failed",
  "data": {
    "errors": [
      {
        "field": "expire_days",
        "message": "Value must be non-negative"
      }
    ]
  }
}

Reload Configuration

POST /config/reload

Reload all configuration from the configuration file. Equivalent to re-reading config.yaml and applying it to the running engine.

Response example:

{
  "code": 0,
  "message": "success",
  "data": {
    "reloaded_plugins": ["mp4", "snap", "transcode"],
    "errors": []
  }
}

WebSocket Real-time Notifications

You can receive real-time configuration change notifications through a WebSocket connection:

ws://host:port/config/ws

Connection Example

const ws = new WebSocket('ws://localhost:8080/config/ws');

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log('Config changed:', msg);
};

Notification Message Format

{
  "type": "config_updated",
  "scope": "plugin",
  "plugin": "mp4",
  "fields": ["record_path", "expire_days"],
  "timestamp": "2026-03-18T14:30:00Z",
  "operator": "admin"
}

Field	Description
`type`	Event type: `config_updated`, `config_reloaded`
`scope`	Change scope: `global` or `plugin`
`plugin`	Plugin name (when scope is `plugin`)
`fields`	List of changed fields
`timestamp`	Change timestamp
`operator`	Operator identifier

Sensitive Configuration Encryption

Monibuca uses AES-256-GCM to encrypt sensitive configuration fields (such as keys, passwords) at rest. Encrypted fields are marked as sensitive: true in the Schema and displayed as masked values in API responses:

{
  "auth": {
    "secret": "***"
  }
}

When writing, provide the plaintext value and the engine will automatically encrypt it for storage.