LEDMatrix/docs/REST_API_REFERENCE.md

LEDMatrix REST API Reference

Reference for the REST API served by the LEDMatrix web interface.

Base URL: http://your-pi-ip:5000/api/v3

Most endpoints answer JSON in this envelope:

{
  "status": "success" | "error",
  "data": { ... },
  "message": "Optional message"
}

Not every endpoint follows it exactly. Where a response puts fields at the top level instead of under data (install-from-url, registry-from-url, the auth endpoints, upload endpoints, system/git-info, system/check-update), the entry below says so.

Table of Contents

• Configuration
• Display Control
• Plugins
• Plugin Store
• System
• Backup and Restore
• Fonts
• Cache
• WiFi
• Streams
• Logs
• Error tracking
• Health and Status
• Schedule (dim/power)
• Integrations
• Plugin-specific endpoints
• Starlark Apps
• Skins

The API blueprint is the api_v3 package in web_interface/blueprints/api_v3/ (one module per area: config.py, display.py, plugins.py, system.py, backup.py, fonts.py, misc.py, wifi.py, starlark.py). web_interface/app.py registers it at /api/v3 (app.register_blueprint(api_v3, url_prefix='/api/v3')). The three SSE endpoints (/api/v3/stream/*) are defined directly on the Flask app in app.py (stream_stats, stream_display, stream_logs). test/fixtures/api_v3_url_map.json is the canonical list of blueprint routes (116 URL rules); a test fails if the code and that fixture differ.

---

Configuration

Get Main Configuration

GET /api/v3/config/main

Return config/config.json. Fields whose names look like credentials (api_key, token, password, secret, ...) are blanked to "" in the response; config/config_secrets.json values are never included.

Response:

{
  "status": "success",
  "data": {
    "timezone": "America/New_York",
    "location": {
      "city": "New York",
      "state": "NY",
      "country": "US"
    },
    "display": { ... },
    "plugin_system": { ... }
  }
}

Save Main Configuration

POST /api/v3/config/main

Update the main configuration. Accepts JSON (Content-Type: application/json) or form data. The body uses the web UI's flat field names, which the handler maps into the nested config:

Fields	Stored at
timezone, city, state, country	timezone, location.*
web_display_autostart, auto_update_enabled	web_display_autostart, auto_update.enabled
plugins_directory (and the unused legacy flags auto_discover, auto_load_enabled, development_mode, stored only when sent)	plugin_system.*
target_fps (30-200)	target_fps
rows, cols, chain_length, parallel, brightness, hardware_mapping, pwm_bits, led_rgb_sequence, panel_type, pixel_mapper_config, disable_hardware_pulsing, inverse_colors, show_refresh_rate, ...	display.hardware.*
gpio_slowdown, rp1_rio	display.runtime.*
use_short_date_format	display.use_short_date_format
max_dynamic_duration_seconds	display.dynamic_duration.max_duration_seconds
double_sided_*, vegas_*, sync_*	display.double_sided, display.vegas_scroll, sync
<name>_duration, default_duration, duration__<mode>	display.display_durations.*
plugin_rotation_order (list of plugin ids)	display.plugin_rotation_order

Any other top-level key is deep-merged into the config as given.

A JSON body changes only the keys it contains; everything else keeps its stored value. (Form posts from the web UI send every field of a tab, and there an unchecked checkbox — which the browser omits — is saved as false.)

Request Body (JSON):

{
  "timezone": "America/New_York",
  "city": "New York",
  "brightness": 90
}

Response:

{
  "status": "success",
  "message": "Configuration saved successfully"
}

Invalid values (e.g. an out-of-range target_fps, a hardware option the Raspberry Pi 5 driver cannot use) are rejected with 400 and nothing is saved.

Get Schedule Configuration

GET /api/v3/config/schedule

Retrieve the current on/off schedule.

Response:

{
  "status": "success",
  "data": {
    "enabled": true,
    "mode": "global",
    "start_time": "07:00",
    "end_time": "23:00"
  }
}

Per-day mode response:

{
  "status": "success",
  "data": {
    "enabled": true,
    "mode": "per-day",
    "days": {
      "monday": {
        "enabled": true,
        "start_time": "07:00",
        "end_time": "23:00"
      },
      "tuesday": { ... }
    }
  }
}

Save Schedule Configuration

POST /api/v3/config/schedule

Replace the schedule configuration.

Request Body (Global mode):

{
  "enabled": true,
  "mode": "global",
  "start_time": "07:00",
  "end_time": "23:00"
}

Request Body (Per-day mode, flat form-field names):

{
  "enabled": true,
  "mode": "per-day",
  "monday_enabled": true,
  "monday_start": "07:00",
  "monday_end": "23:00",
  "tuesday_enabled": true,
  "tuesday_start": "08:00",
  "tuesday_end": "22:00"
}

A day whose <day>_enabled key is absent counts as enabled, with default times 07:00-23:00. At least one day must be enabled.

Response:

{
  "status": "success",
  "message": "Schedule configuration saved successfully"
}

Get Secrets Configuration

GET /api/v3/config/secrets

Retrieve config/config_secrets.json with every set value replaced by eight bullet characters ("••••••••"). Empty values and YOUR_* placeholders are returned as-is, so a client can tell "set" from "not set".

Response:

{
  "status": "success",
  "data": {
    "ledmatrix-weather": {
      "api_key": "••••••••"
    }
  }
}

Save Raw Configuration

POST /api/v3/config/raw/main

Replace config/config.json with the JSON body (advanced use only).

POST /api/v3/config/raw/secrets

Save the secrets file (advanced use only). Masked values ("••••••••") and blank strings in the body are dropped, and the rest is merged onto the stored secrets, so posting back the GET response unchanged changes nothing. A secret cannot be cleared by blanking it here.

---

Display Control

Get Current Display

GET /api/v3/display/current

Get the latest display snapshot as a base64 PNG (image is null when no snapshot is available).

Response:

{
  "status": "success",
  "data": {
    "timestamp": 1234567890.123,
    "width": 128,
    "height": 32,
    "image": "base64_encoded_image_data"
  }
}

Get Current Display Status

GET /api/v3/display/current-status

The mode and plugin the display service is currently showing, as published by the display process (stale after 120 seconds).

Response:

{
  "status": "success",
  "data": {
    "mode": "nfl_live",
    "plugin_id": "football-scoreboard",
    "last_updated": 1234567890.123
  }
}

When nothing has been published, every field is null.

List Display Modes

GET /api/v3/display/modes

Every display mode that can be requested on-demand, with the plugin that owns it. This is the list the force-display dialog offers.

Send the reported plugin_id alongside mode when starting an on-demand display: /display/on-demand/start falls back to find_plugin_for_mode when plugin_id is omitted, and that lookup only sees modes declared in a static manifest — a plugin whose modes are generated (each installed Starlark app is one) returns 404 there.

Triggers plugin discovery, which is otherwise lazy — so a caller that never opens the dashboard still gets the full list.

Query Parameters:

• include_disabled (optional): 1 to include modes belonging to disabled plugins. They are still valid on-demand targets — the controller enables the plugin for the duration of the request — and are reported with "enabled": false.

Response:

{
  "status": "success",
  "data": {
    "modes": [
      {
        "mode": "nfl_live",
        "plugin_id": "football-scoreboard",
        "plugin_name": "Football Scoreboard",
        "name": "nfl_live",
        "enabled": true
      },
      {
        "mode": "clock-simple",
        "plugin_id": "clock-simple",
        "plugin_name": "Simple Clock",
        "name": "Simple Clock",
        "enabled": true
      }
    ]
  }
}

name is a label for a dropdown: a single-mode plugin's own name, or the raw mode string for a multi-mode plugin, since there is no per-mode name anywhere.

On-Demand Display Status

GET /api/v3/display/on-demand/status

Get the current on-demand display state.

Response:

{
  "status": "success",
  "data": {
    "state": {
      "active": true,
      "plugin_id": "football-scoreboard",
      "mode": "nfl_live",
      "duration": 45,
      "pinned": true,
      "status": "running",
      "last_updated": 1234567890.123
    },
    "service": {
      "active": true,
      "returncode": 0,
      "stdout": "active",
      "stderr": ""
    }
  }
}

With no on-demand request, state is {"active": false, "status": "idle", "last_updated": null}.

Start On-Demand Display

POST /api/v3/display/on-demand/start

Request a specific plugin to display on-demand.

Request Body:

{
  "plugin_id": "football-scoreboard",
  "mode": "nfl_live",
  "duration": 45,
  "pinned": true,
  "start_service": true
}

Parameters (at least one of plugin_id and mode is required):

• plugin_id (string, optional): Plugin identifier
• mode (string, optional): Display mode name (plugin_id inferred if not provided)
• duration (number, optional): Duration in seconds (0 = until stopped)
• pinned (boolean, optional): Pin display (pause rotation)
• start_service (boolean, optional): (Re)start the display service so it picks the request up (default: true)

Response:

{
  "status": "success",
  "data": {
    "request_id": "uuid-here",
    "plugin_id": "football-scoreboard",
    "mode": "nfl_live",
    "duration": 45,
    "pinned": true,
    "service": { "active": true, "returncode": 0, "stdout": "", "stderr": "" }
  }
}

service is null when start_service is false.

Stop On-Demand Display

POST /api/v3/display/on-demand/stop

Stop the current on-demand display.

Request Body:

{
  "stop_service": false
}

Parameters:

• stop_service (boolean, optional): Also stop the display service (default: false)

Response:

{
  "status": "success",
  "data": {
    "request_id": "uuid-here",
    "service": null
  }
}

---

Plugins

Get Installed Plugins

GET /api/v3/plugins/installed

List all installed plugins with their status and metadata.

Response:

{
  "status": "success",
  "data": {
    "plugins": [
      {
        "id": "football-scoreboard",
        "name": "Football Scoreboard",
        "version": "1.2.3",
        "latest_version": "1.2.4",
        "update_available": true,
        "author": "ChuckBuilds",
        "category": "Sports",
        "description": "NFL and NCAA Football scores",
        "tags": ["sports", "football", "nfl"],
        "enabled": true,
        "verified": true,
        "loaded": true,
        "state": "loaded",
        "error_info": null,
        "last_updated": "2025-01-15T10:30:00Z",
        "last_commit": "abc1234",
        "last_commit_message": "feat: Add live game updates",
        "branch": "main",
        "web_ui_actions": [],
        "vegas_mode": null,
        "vegas_content_type": null
      }
    ]
  }
}

Get Plugin Configuration

GET /api/v3/plugins/config?plugin_id=<plugin_id>

Get a plugin's configuration, with schema defaults filled in for keys that are not stored. data is the configuration object itself.

Query Parameters:

• plugin_id (required): Plugin identifier

Response:

{
  "status": "success",
  "data": {
    "enabled": true,
    "display_duration": 30,
    "favorite_teams": ["TB", "DAL"]
  }
}

Save Plugin Configuration

POST /api/v3/plugins/config

Update a plugin's configuration. With a JSON body, the keys in config are merged onto the plugin's stored configuration: keys you do not send keep their stored values. Fields the schema marks "x-secret": true are written to config/config_secrets.json instead of config.json. The web UI posts form data instead (?plugin_id= in the query string, fields as form fields).

Request Body:

{
  "plugin_id": "football-scoreboard",
  "config": {
    "display_duration": 30,
    "favorite_teams": ["TB", "DAL"]
  }
}

Response:

{
  "status": "success",
  "message": "Plugin football-scoreboard configuration saved successfully"
}

A config that fails schema validation is rejected with 400 and nothing is saved.

Get Plugin Schema

GET /api/v3/plugins/schema?plugin_id=<plugin_id>

Get the JSON schema for a plugin's configuration. A plugin without a config_schema.json gets a minimal default schema.

Query Parameters:

• plugin_id (required): Plugin identifier

Response:

{
  "status": "success",
  "data": {
    "schema": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean",
          "default": true
        },
        "display_duration": {
          "type": "number",
          "minimum": 1,
          "maximum": 300
        }
      }
    }
  }
}

Reset Plugin Configuration

POST /api/v3/plugins/config/reset

Reset a plugin's configuration to its schema defaults.

Request Body:

{
  "plugin_id": "football-scoreboard",
  "preserve_secrets": true
}

Response:

{
  "status": "success",
  "message": "Plugin football-scoreboard configuration reset to defaults",
  "data": { "config": { ... } }
}

Toggle Plugin

POST /api/v3/plugins/toggle

Enable or disable a plugin. A plugin_id of the form starlark:<app_id> toggles a Starlark app.

Request Body:

{
  "plugin_id": "football-scoreboard",
  "enabled": true
}

Response:

{
  "status": "success",
  "message": "Plugin football-scoreboard enabled successfully"
}

Install Plugin

POST /api/v3/plugins/install

Install a plugin from the plugin store.

Request Body:

{
  "plugin_id": "football-scoreboard",
  "branch": "main"
}

branch is optional.

Response (queued; poll /plugins/operation/<operation_id>):

{
  "status": "success",
  "data": { "operation_id": "uuid-here" },
  "message": "Plugin football-scoreboard installation queued"
}

When the operation queue is unavailable the install runs synchronously and the response has only a message.

Uninstall Plugin

POST /api/v3/plugins/uninstall

Remove an installed plugin.

Request Body:

{
  "plugin_id": "football-scoreboard",
  "preserve_config": false
}

Response (queued):

{
  "status": "success",
  "data": { "operation_id": "uuid-here" },
  "message": "Plugin uninstallation queued"
}

Update Plugin

POST /api/v3/plugins/update

Update a plugin to the latest version. Runs synchronously.

Request Body:

{
  "plugin_id": "football-scoreboard"
}

Response:

{
  "status": "success",
  "message": "Plugin football-scoreboard updated ...",
  "data": {
    "last_updated": "2025-01-15T10:30:00Z",
    "commit": "abc1234..."
  }
}

Install Plugin from URL

POST /api/v3/plugins/install-from-url

Install a plugin directly from a GitHub repository URL. Runs synchronously.

Request Body:

{
  "repo_url": "https://github.com/user/ledmatrix-my-plugin",
  "branch": "main",
  "plugin_path": null
}

Parameters:

• repo_url (required): GitHub repository URL
• branch (optional): Branch name (default: main, then master)
• plugin_path (optional): Path within the repository, for monorepo plugins
• plugin_id (optional): Plugin id, for monorepo installations

Response (fields at the top level):

{
  "status": "success",
  "message": "Plugin my-plugin installed successfully",
  "plugin_id": "my-plugin",
  "name": "My Plugin",
  "branch": "main"
}

Load Registry from URL

POST /api/v3/plugins/registry-from-url

Load a plugins.json registry from a GitHub repository URL.

Request Body:

{
  "repo_url": "https://github.com/user/ledmatrix-plugins"
}

Response (fields at the top level):

{
  "status": "success",
  "plugins": [
    {
      "id": "plugin-1",
      "name": "Plugin One",
      "description": "..."
    }
  ],
  "registry_url": "https://github.com/user/ledmatrix-plugins"
}

Get Plugin Health

GET /api/v3/plugins/health

Get health state for all installed plugins, keyed by plugin id.

Response:

{
  "status": "success",
  "data": {
    "football-scoreboard": {
      "plugin_id": "football-scoreboard",
      "circuit_state": "closed",
      "consecutive_failures": 0,
      "total_failures": 2,
      "total_successes": 1500,
      "success_rate": 99.87,
      "last_success_time": 1234567890.123,
      "last_failure_time": 1234560000.0,
      "last_error": null,
      "is_healthy": true,
      "degraded": false,
      "degraded_reason": null,
      "circuit_opened_time": null,
      "half_open_start_time": null
    }
  }
}

Get Plugin Health (Single)

GET /api/v3/plugins/health/<plugin_id>

Health state for one plugin; data has the same fields as one entry above. Answers 503 when health tracking is unavailable.

Reset Plugin Health

POST /api/v3/plugins/health/<plugin_id>/reset

Reset health state for a plugin (manual recovery).

Response:

{
  "status": "success",
  "message": "Health state reset for plugin football-scoreboard"
}

Get Plugin Metrics

GET /api/v3/plugins/metrics

Get resource usage metrics for all installed plugins, keyed by plugin id.

Response:

{
  "status": "success",
  "data": {
    "football-scoreboard": {
      "plugin_id": "football-scoreboard",
      "memory_mb": 24.5,
      "cpu_percent": 3.2,
      "execution_time": 0.12,
      "avg_execution_time": 0.1,
      "min_execution_time": 0.05,
      "max_execution_time": 0.9,
      "call_count": 500,
      "last_update_time": 1234567890.123,
      "limits": {
        "max_memory_mb": 50,
        "max_cpu_percent": 50,
        "max_execution_time": 5.0,
        "warning_threshold": 0.8
      }
    }
  }
}

limits (and usage percentages derived from it) appear only when limits are configured for the plugin.

Get Plugin Metrics (Single)

GET /api/v3/plugins/metrics/<plugin_id>

Metrics for one plugin; data has the same fields as one entry above.

Reset Plugin Metrics

POST /api/v3/plugins/metrics/<plugin_id>/reset

Reset metrics for a plugin.

Get/Set Plugin Limits

GET /api/v3/plugins/limits/<plugin_id>

Get a plugin's resource limits. data is null when none are configured.

Response:

{
  "status": "success",
  "data": {
    "max_memory_mb": 50,
    "max_cpu_percent": 50,
    "max_execution_time": 5.0,
    "warning_threshold": 0.8
  }
}

POST /api/v3/plugins/limits/<plugin_id>

Set a plugin's resource limits. The body replaces all four limits: a key you omit is stored as no limit (warning_threshold defaults to 0.8).

Request Body:

{
  "max_memory_mb": 50,
  "max_cpu_percent": 50,
  "max_execution_time": 5.0,
  "warning_threshold": 0.8
}

Get Plugin State

GET /api/v3/plugins/state

Get the state manager's record for every plugin, keyed by plugin id. Pass ?plugin_id=<id> for one plugin (data is then that record).

Response:

{
  "status": "success",
  "data": {
    "football-scoreboard": {
      "plugin_id": "football-scoreboard",
      "status": "loaded",
      "enabled": true,
      "version": "1.2.3",
      "installed_at": "2025-01-15T10:30:00",
      "last_updated": "2025-01-15T10:30:00",
      "config_version": 1,
      "metadata": {}
    }
  }
}

Reconcile Plugin State

POST /api/v3/plugins/state/reconcile

Reconcile plugin state across config, disk and the state manager.

Request Body (optional):

{
  "force": false
}

Response:

{
  "status": "success",
  "message": "...",
  "data": {
    "inconsistencies_found": 1,
    "inconsistencies_fixed": 1,
    "inconsistencies_manual": 0,
    "inconsistencies": [
      {"plugin_id": "...", "type": "...", "description": "...", "fix_action": "..."}
    ],
    "fixed": [ ... ],
    "manual_fix_required": [ ... ]
  }
}

Get Reconciliation Status

GET /api/v3/plugins/reconciliation-status

Result of the last startup reconciliation, as written by the display service.

Response:

{
  "status": "success",
  "data": {
    "done": true,
    "unresolved": []
  }
}

Before a run has finished, data is {"done": false, "unresolved": []}.

Get Plugin Operation

GET /api/v3/plugins/operation/<operation_id>

Get status of a queued plugin operation (install, uninstall).

Response:

{
  "status": "success",
  "data": {
    "operation_id": "uuid-here",
    "operation_type": "install",
    "plugin_id": "football-scoreboard",
    "parameters": {},
    "status": "completed",
    "progress": 100,
    "message": "Installation completed successfully",
    "error": null,
    "result": { ... },
    "created_at": "2025-01-15T10:30:00",
    "started_at": "2025-01-15T10:30:01",
    "completed_at": "2025-01-15T10:30:20"
  }
}

Get Operation History

GET /api/v3/plugins/operation/history?limit=50

Get the plugin operation audit log. data is a list.

Query Parameters:

• limit (optional): Maximum number of records (default: 50)
• plugin_id (optional): Only records for this plugin
• operation_type (optional): Only records of this type (install, update, enable, ...)

Response:

{
  "status": "success",
  "data": [
    {
      "operation_id": "uuid-here",
      "operation_type": "install",
      "plugin_id": "football-scoreboard",
      "timestamp": "2025-01-15T10:30:00",
      "status": "success",
      "user": null,
      "details": null,
      "error": null
    }
  ]
}

Clear Operation History

DELETE /api/v3/plugins/operation/history

Clear the operation audit log.

Execute Plugin Action

POST /api/v3/plugins/action

Execute an action declared in the plugin manifest's web_ui_actions. See PLUGIN_WEB_UI_ACTIONS.md.

Request Body:

{
  "plugin_id": "football-scoreboard",
  "action_id": "refresh_games",
  "params": {}
}

Response (fields at the top level; a script that prints JSON can return its own object instead):

{
  "status": "success",
  "message": "Action completed successfully",
  "output": "script stdout"
}

Upload Plugin Assets

POST /api/v3/plugins/assets/upload

Upload images for a plugin. Stored under assets/plugins/<plugin_id>/uploads/.

Request: Multipart form data

• plugin_id (required): Plugin identifier
• files (required, repeatable, up to 10): PNG, JPEG, BMP or GIF images, 5 MB each, 50 MB total per plugin

Response (fields at the top level):

{
  "status": "success",
  "uploaded_files": [
    {
      "id": "uuid-here",
      "filename": "image_1700000000_abcd1234.png",
      "path": "assets/plugins/football-scoreboard/uploads/image_1700000000_abcd1234.png",
      "size": 1024,
      "uploaded_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total_files": 3
}

Delete Plugin Asset

POST /api/v3/plugins/assets/delete

Delete an uploaded plugin image by its id (the id from upload or list).

Request Body:

{
  "plugin_id": "football-scoreboard",
  "image_id": "uuid-here"
}

List Plugin Assets

GET /api/v3/plugins/assets/list?plugin_id=<plugin_id>

List uploaded images for a plugin.

Query Parameters:

• plugin_id (required): Plugin identifier

Response:

{
  "status": "success",
  "data": {
    "assets": [
      {
        "id": "uuid-here",
        "filename": "image_1700000000_abcd1234.png",
        "path": "assets/plugins/football-scoreboard/uploads/image_1700000000_abcd1234.png",
        "size": 1024,
        "uploaded_at": "2025-01-15T10:30:00Z",
        "original_filename": "logo.png"
      }
    ]
  }
}

Authenticate Spotify

POST /api/v3/plugins/authenticate/spotify

Spotify OAuth for the music plugin (ledmatrix-music; the plugin is fixed, not taken from the body). Two steps: call with an empty body to get the authorization URL, then call again with the URL Spotify redirected to.

Request Body (step 2):

{
  "redirect_url": "http://127.0.0.1:8888/callback?code=..."
}

Response (step 1, fields at the top level):

{
  "status": "success",
  "message": "Authorization URL generated",
  "auth_url": "https://accounts.spotify.com/authorize?..."
}

Step 2 returns status, message and the script's output.

Authenticate YouTube Music

POST /api/v3/plugins/authenticate/ytm

Run the music plugin's YouTube Music authentication script. No body. Returns status, message and the script's output.

Upload Calendar Credentials

POST /api/v3/plugins/calendar/upload-credentials

Upload the Google OAuth client file for the calendar plugin.

Request: Multipart form data

• file (required): credentials.json (JSON, max 1 MB)

Authenticate Calendar

POST /api/v3/plugins/calendar/authenticate

Google OAuth for the calendar plugin, in two steps. Step 1 (no body) returns the consent URL. Step 2 posts the URL Google redirected to (it fails to load in the browser, but its address carries the authorization code):

{
  "redirect_url": "http://localhost/?code=..."
}

Requires credentials.json to have been uploaded first (400 otherwise).

---

Plugin Store

List / Search Store Plugins

GET /api/v3/plugins/store/list

List plugins from the registry and saved repositories. The same endpoint searches.

Query Parameters:

• query (optional): Text search over name, description, id
• category (optional): Category filter
• tags (optional, repeatable): Tag filter
• fetch_commit_info (optional): false to skip fetching commit metadata from GitHub (default: fetched)

Response:

{
  "status": "success",
  "data": {
    "plugins": [
      {
        "id": "football-scoreboard",
        "name": "Football Scoreboard",
        "author": "ChuckBuilds",
        "category": "Sports",
        "description": "NFL and NCAA Football scores",
        "tags": ["sports"],
        "stars": 0,
        "verified": true,
        "repo": "https://github.com/ChuckBuilds/ledmatrix-plugins",
        "last_updated": "2025-01-15",
        "last_updated_iso": "2025-01-15T10:30:00Z",
        "last_commit": "abc1234",
        "last_commit_message": "...",
        "last_commit_author": "...",
        "version": "1.2.3",
        "branch": "main",
        "default_branch": "main",
        "plugin_path": "plugins/football-scoreboard"
      }
    ]
  }
}

Get GitHub Status

GET /api/v3/plugins/store/github-status

Whether a GitHub token is configured and valid.

Response:

{
  "status": "success",
  "data": {
    "token_status": "valid",
    "authenticated": true,
    "rate_limit": 5000,
    "message": "GitHub API authenticated",
    "error": null
  }
}

token_status is none, valid or invalid; rate_limit is the nominal hourly limit (60 unauthenticated), not a live count.

Refresh Plugin Store

POST /api/v3/plugins/store/refresh

Force refresh of the registry cache.

Response:

{
  "status": "success",
  "message": "Plugin store refreshed",
  "plugin_count": 42
}

Get Saved Repositories

GET /api/v3/plugins/saved-repositories

Get the list of saved custom plugin repositories.

Response:

{
  "status": "success",
  "data": {
    "repositories": [
      {
        "url": "https://github.com/user/ledmatrix-plugins",
        "name": "ledmatrix-plugins",
        "type": "registry"
      }
    ]
  }
}

Save Repository

POST /api/v3/plugins/saved-repositories

Save a custom plugin repository. Returns the updated list in data.repositories.

Request Body:

{
  "repo_url": "https://github.com/user/ledmatrix-plugins",
  "name": "Custom Plugins"
}

Delete Saved Repository

DELETE /api/v3/plugins/saved-repositories

Remove a saved repository. Returns the updated list in data.repositories.

Request Body:

{
  "repo_url": "https://github.com/user/ledmatrix-plugins"
}

---

System

Get System Status

GET /api/v3/system/status

Get system status and metrics (cached for 10 seconds).

Response:

{
  "status": "success",
  "data": {
    "timestamp": 1234567890.123,
    "uptime": "3d 4h",
    "uptime_seconds": 273600,
    "service_active": true,
    "cpu_percent": 25.5,
    "memory_used_percent": 45.2,
    "memory_total_mb": 3794.0,
    "memory_used_mb": 1715.0,
    "memory_available_mb": 1900.0,
    "cpu_temp": 45.0,
    "disk_used_percent": 60.0,
    "disk_total_gb": 29.0,
    "disk_used_gb": 17.4
  }
}

Get System Version

GET /api/v3/system/version

Get LEDMatrix repository version.

Response:

{
  "status": "success",
  "data": {
    "version": "v2.4-10-g1234567"
  }
}

Check for Update

GET /api/v3/system/check-update

Whether origin/main has commits the checkout lacks. Cached briefly. Fields at the top level (no envelope):

{
  "update_available": true,
  "remote_sha": "abc123...",
  "commits_behind": 3
}

When git cannot run the check, the response also carries "check_failed": true and an error explaining why.

Automatic Update Status

GET /api/v3/system/auto-update

Weekly automatic-update status for the General tab and the Overview banner: last_run, summary, status, next_due, alert, alert_id, verifier_installed, setup_status, setup_message, verifying (in data).

POST /api/v3/system/auto-update/dismiss

Hide the current automatic-update alert until a new one replaces it.

{
  "alert_id": "..."
}

Git Info

GET /api/v3/system/git-info

Branch, dirty state, recent commits and remote for the Tools tab. Fields at the top level: branch, dirty, status, recent_commits, remote_url (credentials scrubbed), upstream, can_pull.

Git Branches

GET /api/v3/system/git-branches

Fetches origin and lists branches to switch to: current, upstream, local (list), remote_only (list), at the top level.

Execute System Action

POST /api/v3/system/action

Execute system-level actions. JSON or form data.

Request Body:

{
  "action": "restart_display_service"
}

Available Actions:

• start_display: Start the display service
• stop_display: Stop the display service
• restart_display_service: Restart the display service
• restart_web_service: Restart the web interface service
• enable_autostart: Enable display service autostart
• disable_autostart: Disable display service autostart
• reboot_system: Reboot the Raspberry Pi
• shutdown_system: Power off the Raspberry Pi
• git_pull: Update LEDMatrix from git (the Update button)
• checkout_branch: Switch branch; takes branch and optional stash
• force_git_reset: git reset --hard origin/main
• install_base_requirements: pip install requirements.txt and web_interface/requirements.txt
• install_plugin_requirements: pip install every plugin's requirements.txt
• clear_pycache: Delete __pycache__ directories

Response (service actions):

{
  "status": "success",
  "message": "Action completed"
}

A failed service action returns "status": "error" with returncode and stderr. git_pull returns message, restart_required and dependency_failures; the install actions return output or details.

---

Backup and Restore

Backups are ZIP files kept in the backup export directory.

Preview

GET /api/v3/backup/preview

Summary of what a new backup would include.

List

GET /api/v3/backup/list

Stored backups, newest first. data is a list of {"filename", "size", "created_at"}.

Export

POST /api/v3/backup/export

Create a backup. Returns {"status": "success", "filename": "..."}.

Validate

POST /api/v3/backup/validate

Check an uploaded backup and return its manifest in data.

Request: Multipart form data

• backup_file (required): the ZIP

Restore

POST /api/v3/backup/restore

Restore an uploaded backup.

Request: Multipart form data

• backup_file (required): the ZIP
• options (optional): JSON object; keys restore_config, restore_secrets, restore_wifi, restore_fonts, restore_plugin_uploads, reinstall_plugins (each defaults to true; unknown keys are rejected)

A partial restore answers 500 with "status": "error", a message listing what did and didn't restore, and the result in data.

Download

GET /api/v3/backup/download/<filename>

Download a stored backup.

Delete

DELETE /api/v3/backup/<filename>

Delete a stored backup.

---

Fonts

Get Font Catalog

GET /api/v3/fonts/catalog

Fonts in assets/fonts/, keyed by file name without extension.

Response:

{
  "status": "success",
  "data": {
    "catalog": {
      "press_start": {
        "filename": "press_start.ttf",
        "family_name": "Press Start 2P",
        "display_name": "Press Start 2P",
        "path": "assets/fonts/press_start.ttf",
        "type": "ttf",
        "is_system": true,
        "scalable": true,
        "native_size": null,
        "metadata": { ... }
      }
    }
  }
}

Get Font Tokens

GET /api/v3/fonts/tokens

Get font size token definitions.

Response:

{
  "status": "success",
  "data": {
    "tokens": {
      "xs": 6,
      "sm": 8,
      "md": 10,
      "lg": 12,
      "xl": 14,
      "xxl": 16
    }
  }
}

Upload Font

POST /api/v3/fonts/upload

Upload a custom font file. It is saved as assets/fonts/<font_family><ext>.

Request: Multipart form data

• font_file (required): .ttf, .otf or .bdf, max 10 MB
• font_family (required): name for the font (letters, numbers, _, -)

Response (fields at the top level):

{
  "status": "success",
  "message": "Font custom_font uploaded successfully",
  "font_family": "custom_font",
  "filename": "custom_font.ttf",
  "path": "assets/fonts/custom_font.ttf"
}

Delete Font

DELETE /api/v3/fonts/<font_family>

Delete an uploaded font (<font_family> is the file name without extension). System fonts answer 403.

Font Preview

GET /api/v3/fonts/preview?font=<filename>&text=<sample>&size=12

Render text in a font, for the web UI font picker. BDF fonts are not previewed (400).

Query Parameters:

• font (required): font file name in assets/fonts/ (e.g. press_start.ttf)
• text (optional): up to 100 characters (default Sample Text 123)
• size (optional): 4-72 (default 12)
• bg, fg (optional): hex colours without # (default 000000 / ffffff)

Response:

{
  "status": "success",
  "data": {
    "image": "data:image/png;base64,...",
    "width": 140,
    "height": 32
  }
}

Font overrides (/api/v3/fonts/overrides) were removed. Per-plugin font choices are made in each plugin's own settings.

---

Cache

List Cache Entries

GET /api/v3/cache/list

List cache files.

Response:

{
  "status": "success",
  "data": {
    "cache_files": [ ... ],
    "cache_dir": "/var/cache/ledmatrix",
    "total_files": 12
  }
}

Delete Cache Entry

POST /api/v3/cache/delete

Delete one cache entry by key. There is no clear-all option here; use scripts/utils/clear_cache.py --clear-all on the Pi for that.

Request Body:

{
  "key": "weather_current_12345"
}

---

WiFi

Get WiFi Status

GET /api/v3/wifi/status

Get current WiFi connection status.

Response:

{
  "status": "success",
  "data": {
    "connected": true,
    "ssid": "MyNetwork",
    "ip_address": "192.168.1.100",
    "signal": 70,
    "ap_mode_active": false,
    "auto_enable_ap_mode": true,
    "last_connect_attempt": null
  }
}

Scan WiFi Networks

GET /api/v3/wifi/scan

Scan for available WiFi networks. data is a list. If AP mode is active it is turned off for the scan and back on afterwards, and message says so.

Response:

{
  "status": "success",
  "data": [
    {
      "ssid": "MyNetwork",
      "signal": 70,
      "security": "WPA2",
      "frequency": 2437
    }
  ]
}

Connect to WiFi

POST /api/v3/wifi/connect

Connect to a WiFi network.

Request Body:

{
  "ssid": "MyNetwork",
  "password": "mypassword"
}

Response: "status": "success" when connected; "status": "pending" (with data.ssid) when the connection continues in the background — poll /wifi/status and read last_connect_attempt. A wrong password answers 400 with "error_type": "wrong_password".

Disconnect from WiFi

POST /api/v3/wifi/disconnect

Disconnect from current WiFi network.

Enable Access Point Mode

POST /api/v3/wifi/ap/enable

Enable WiFi access point mode. Optional body {"force": true}.

Disable Access Point Mode

POST /api/v3/wifi/ap/disable

Disable WiFi access point mode.

Get Auto-Enable AP Setting

GET /api/v3/wifi/ap/auto-enable

Response:

{
  "status": "success",
  "data": {
    "auto_enable_ap_mode": true
  }
}

Set Auto-Enable AP

POST /api/v3/wifi/ap/auto-enable

Request Body:

{
  "auto_enable_ap_mode": true
}

WiFi Radio

GET /api/v3/wifi/radio

Radio state: data.enabled (null if unknown), data.ethernet_connected, data.available.

POST /api/v3/wifi/radio

Turn the WiFi radio on or off. Turning it off is refused unless Ethernet is connected or force is true, so you don't cut off your own connection.

{
  "enabled": false,
  "force": false
}

---

Streams

Server-Sent Events, defined in web_interface/app.py. Each event is one data: <json> line; idle connections get : heartbeat comments.

System Statistics Stream

GET /api/v3/stream/stats

data: {"timestamp": 1234567890.1, "uptime": "Running", "service_active": true, "cpu_percent": 25.5, "memory_used_percent": 45.2, "memory_available_mb": 1900.0, "cpu_temp": 45.0, "disk_used_percent": 60.0, "power": {...}}

Display Preview Stream

GET /api/v3/stream/display

data: {"timestamp": 1234567890.123, "width": 128, "height": 32, "image": "base64_data_here"}

Service Logs Stream

GET /api/v3/stream/logs

Each event carries the latest journal lines for ledmatrix and ledmatrix-web as one text block:

data: {"timestamp": 1234567890.123, "logs": "2025-01-15T10:30:00+0000 host python[123]: ..."}

---

Logs

Get Logs

GET /api/v3/logs

The last 100 journal lines for ledmatrix.service and ledmatrix-web.service, as one text block. Takes no parameters.

Response:

{
  "status": "success",
  "data": {
    "logs": "2025-01-15T10:30:00+0000 host python[123]: Plugin loaded: football-scoreboard\n..."
  }
}

---

Error tracking

Get Error Summary

GET /api/v3/errors/summary

Aggregated counts, detected patterns and recent errors across plugins and core components.

Get Plugin Errors

GET /api/v3/errors/plugin/<plugin_id>

Error health and statistics for one plugin.

Clear Errors

POST /api/v3/errors/clear

Clear error records older than max_age_hours (default 24, 1-8760). Returns data.cleared_count.

{
  "max_age_hours": 24
}

---

Health and Status

Health Check

GET /api/v3/health

Health of the web interface, display service, config file, plugin system and display snapshot. data.status is healthy or degraded, with data.services and data.checks.

Hardware Status

GET /api/v3/hardware/status

LED matrix initialization result written by the display service at startup. Before the service has written it, data is {"ok": null, "error": "Display service not yet started"}.

Sync Status

GET /api/v3/sync/status

Live multi-display sync status from the display process; before it has written one, data is {"role", "port", "state": "starting"} from config.

---

Schedule (dim/power)

Get Dim Schedule

GET /api/v3/config/dim-schedule

Read the schedule that lowers brightness at configured times.

Response:

{
  "status": "success",
  "data": {
    "enabled": true,
    "dim_brightness": 30,
    "mode": "per-day",
    "days": {
      "monday": { "enabled": true, "start_time": "20:00", "end_time": "07:00" },
      "tuesday": { ... }
    }
  }
}

In global mode, start_time and end_time sit at the top level instead of days.

Update Dim Schedule

POST /api/v3/config/dim-schedule

Replace the dim schedule. dim_brightness is 0-100 (default 30). In per-day mode the days can be sent either as the days object that GET returns, or as the web form's flat fields (monday_enabled, monday_start, monday_end, ...). A day that is not sent counts as enabled with default times 20:00-07:00; at least one day must be enabled.

---

Integrations

MQTT Bridge

GET /api/v3/integrations/mqtt-bridge

Home Assistant MQTT bridge service state and settings: data.service, data.config_exists, data.config_path, data.config (password omitted), data.password_set, data.env_override_prefix.

PUT /api/v3/integrations/mqtt-bridge/config

Write integrations/mqtt_bridge/bridge_config.json. Only the keys you send change. The password is write-only: omit mqtt_password to keep it, send a value to replace it, or send "clear_password": true. A password with mqtt_tls off is refused unless allow_insecure_mqtt is true. Returns data.password_set and data.restart_required (the bridge must be restarted to pick up changes). See integrations/mqtt_bridge/README.md.

---

Plugin-specific endpoints

A handful of endpoints belong to individual plugins.

Calendar

GET /api/v3/plugins/calendar/list-calendars

List the calendars on the authenticated Google account. Used by the calendar plugin's config UI. Returns calendars at the top level. The upload and authenticate endpoints are under Plugins.

Of The Day

POST /api/v3/plugins/of-the-day/json/upload

Upload JSON data files (multipart field files) as Of-The-Day categories. Returns uploaded_files and total_files at the top level.

POST /api/v3/plugins/of-the-day/json/delete

Delete an uploaded data file.

{
  "file_id": "category_name"
}

Plugin Static Assets

GET /api/v3/plugins/<plugin_id>/static/<path:file_path>

Serve a static file from a plugin's directory. Used internally by the web UI to render plugin previews and icons.

---

Starlark Apps

The Starlark plugin lets you run Tronbyt Starlark apps on the matrix. These endpoints expose its UI.

Status

GET /api/v3/starlark/status

Returns whether the Pixlet binary is installed and the Starlark plugin is operational.

Install Pixlet

POST /api/v3/starlark/install-pixlet

Download and install the Pixlet binary on the Pi.

Apps

GET /api/v3/starlark/apps — list installed Starlark apps GET /api/v3/starlark/apps/<app_id> — get app details DELETE /api/v3/starlark/apps/<app_id> — uninstall an app GET /api/v3/starlark/apps/<app_id>/config — get app config schema PUT /api/v3/starlark/apps/<app_id>/config — update app config POST /api/v3/starlark/apps/<app_id>/render — render app to a frame POST /api/v3/starlark/apps/<app_id>/toggle — enable/disable app ({"enabled": bool}; omit to flip)

Repository (Tronbyt community apps)

GET /api/v3/starlark/repository/categories — list categories GET /api/v3/starlark/repository/browse — every app with metadata (filtering happens client-side; cached for 2 hours) POST /api/v3/starlark/repository/install — install an app: {"app_id": "...", "render_interval": 300, "display_duration": 15}

Upload custom app

POST /api/v3/starlark/upload

Upload a custom Starlark .star file as a new app. Multipart fields: file (required, max 5 MB), name, app_id, render_interval, display_duration.

Editor

A Pixlet editing session for one app. The display is stopped while a session runs.

GET /api/v3/starlark/editor/apps — apps the editor can open (data.apps, data.apps_dir, data.pixlet_available) GET /api/v3/starlark/editor/status — data.running, plus app_id, port, pid, started_at, timeout, seconds_remaining, host_bound while running POST /api/v3/starlark/editor/start — {"app_id": "...", "timeout": 1800, "port": 8080} (timeout and port optional) POST /api/v3/starlark/editor/stop — end the session and restart the display

---

Skins

GET /api/v3/skins

Installed scoreboard skins (optional ?plugin_id= filter). Skins are not supported by the current scoreboard plugins, so the response carries data.supported: false and a data.message; clients must not offer these as selectable. See SKIN_SYSTEM.md.

---

Error Responses

Errors use one of two shapes. Most endpoints answer:

{
  "status": "error",
  "message": "Error description",
  "details": "Additional error details (optional)"
}

Endpoints built on the structured error helper add a code and category:

{
  "status": "error",
  "error_code": "CONFIG_SAVE_FAILED",
  "error_category": "configuration",
  "message": "Error description",
  "details": "optional",
  "context": { },
  "suggested_fixes": [ ]
}

Common HTTP Status Codes:

• 200: Success
• 400: Bad Request (invalid parameters)
• 403: Forbidden (e.g. deleting a system font)
• 404: Not Found (resource doesn't exist)
• 408: Timed out (plugin actions, auth scripts)
• 500: Internal Server Error
• 503: Service Unavailable (feature not available)

---

See Also

• Plugin API Reference - API for plugin developers
• Plugin Development Guide - Complete plugin development guide
• Web Interface README - Web interface documentation