Web Control Center & REST API

The MTM Matrix Signs system includes an asynchronous HTTP REST API and a standalone Web Control Center. This allows dispatchers, control room operators, and external CAD/MDT systems to monitor and manipulate highway matrix signs in real time from any web browser outside the FiveM client.

---

Security Advisory: API Configuration

The built-in Web API exposes an HTTP listener on your FiveM server port (default 30121).

Security Best Practice

If your community or server only utilizes in-game controls (such as the /matrix:menu NUI menu or the MTM-PADUI tablet), it is strongly recommended to disable the Web API by setting Config.EnableWebAPI = false in config.lua. This eliminates unnecessary network exposure.

-- In config.lua:
Config.EnableWebAPI = false -- Set to false if you do not use external website control

If you do choose to enable the Web API (Config.EnableWebAPI = true), always configure a strong, secret API Key in Config.WebApiKey:

Config.WebApiKey = "YOUR_SECURE_SECRET_KEY_HERE"

---

Standalone Web Server (Local Operator Mode)

For local dispatch operators who want a dedicated browser window on a secondary monitor:

1. Navigate to the MTM-MATRIXBORDEN directory on your machine.
2. Run START_WEB_SERVER.bat. This launches node web_server.js on local port 3000.
3. Open your browser at http://localhost:3000.
4. The local server provides a proxy that securely routes API requests to your FiveM server while providing a fullscreen interface.

---

Hosting on an External Web Server

You can deploy the standalone web interface to your own web hosting environment (such as Nginx, Apache, Vercel, or a CAD/MDT subfolder):

1. Upload the entire contents of the web/ directory to your web server.
2. Open web/config.js in your code editor.
3. Configure your server URL, API key, and preferred sync interval as shown in the example below.

window.CONFIG = {
    // The public IP and port of your FiveM server (with resource route)
    SERVER_URL: 'http://YOUR_SERVER_IP:30121/MTM-MATRIXBORDEN',

    // Secret API Key (must match Config.WebApiKey in config.lua)
    API_KEY: 'YOUR_SECURE_SECRET_KEY_HERE',

    // How frequently the web map polls for live server updates (in ms)
    SYNC_INTERVAL: 1500,

    // Default language ('nl' or 'en')
    DEFAULT_LANGUAGE: 'en'
};

---

REST API Reference

All requests must be addressed to http://<SERVER_IP>:<PORT>/MTM-MATRIXBORDEN/api/<ENDPOINT>.

Authentication

If Config.WebApiKey is set in config.lua, every request must provide the API key using one of the following methods:

• HTTP Header: X-Api-Key: YOUR_KEY or Authorization: Bearer YOUR_KEY
• URL Query Parameter: ?apikey=YOUR_KEY

If the key is missing or invalid, the API returns 401 Unauthorized.

---

1. Get Active Matrix Signs (GET /api/active)

Retrieves a real-time list of all currently active matrix signs across the entire map.

• Endpoint: GET /api/active
• Method: GET
• Headers: X-Api-Key: <key> (optional if no key configured)

cURL

curl -X GET "http://YOUR_SERVER_IP:30121/MTM-MATRIXBORDEN/api/active" \
     -H "X-Api-Key: YOUR_SECRET_KEY"

JavaScript (Fetch)

const response = await fetch('http://YOUR_SERVER_IP:30121/MTM-MATRIXBORDEN/api/active', {
    method: 'GET',
    headers: {
        'X-Api-Key': 'YOUR_SECRET_KEY'
    }
});
const data = await response.json();
console.log(data);

Success Response (200 OK):

{
  "success": true,
  "timestamp": 1786997102,
  "activeMarkers": {
    "2517.14_-25.38_97.32": {
      "coords": [2517.14966, -25.38, 97.32],
      "heading": 85.0,
      "marker": "zeventig"
    },
    "2519.50_-24.10_97.32": {
      "coords": [2519.50, -24.10, 97.32],
      "heading": 85.0,
      "marker": "kruis"
    }
  }
}

---

2. Spawn / Update Matrix Signs (POST /api/spawnmarkering)

Sets or updates signs on one or multiple lanes of a matrix gantry.

• Endpoint: POST /api/spawnmarkering
• Method: POST
• Headers: Content-Type: application/json, X-Api-Key: <key>

Request Payload:

{
  "data": [
    {
      "marker": "zeventig",
      "coords": [2517.14966, -25.38, 97.32],
      "heading": 85.0
    },
    {
      "marker": "kruis",
      "coords": [2519.50, -24.10, 97.32],
      "heading": 85.0
    }
  ]
}

Valid marker Values:

• Advisory Speeds:
  • "tien" (10 km/h)
  • "twintig" (20 km/h)
  • "dertig" (30 km/h)
  • "veertig" (40 km/h)
  • "vijftig" (50 km/h)
  • "zestig" (60 km/h)
  • "zeventig" (70 km/h)
  • "tachtig" or "tachtig2" (80 km/h)
  • "negentig" (90 km/h)
  • "honderd" (100 km/h)
  • "honderdtien" (110 km/h)
  • "honderdtwintig" (120 km/h)
  • "honderddertig" (130 km/h)
• Traffic Control Symbols:
  • "kruis" (Red Cross / Lane Closed)
  • "ophef" (Clear / End of Restrictions)
  • "pijl links" (Flashing Lane Change Arrow Left)
  • "pijl rechts" (Flashing Lane Change Arrow Right)
  • "pijlg" (Green Arrow / Lane Open)
• Warning Signs:
  • "file" (Traffic Jam / Congestion)
  • "glad" (Slippery Road / Snowflake — Note: use "glad", not "gladheid")
  • "ongeval" (Accident / Incident)
  • "uitroepteken" (General Danger / Hazard)
• Off / Empty: "" or null

Case-Sensitive Prop Names

Values must be exact lowercase strings matching the FiveM 3D prop model names. Do not send numeric digits (e.g. use "honderdtwintig", not 120).

Success Response (200 OK):

{
  "success": true,
  "message": "Matrix signs updated",
  "activeMarkers": { ... }
}

---

3. Reset / Clear Matrix Signs (POST /api/resetmarkering)

Deactivates signs on specified gantry lanes and removes active 3D props in-game.

• Endpoint: POST /api/resetmarkering
• Method: POST
• Headers: Content-Type: application/json, X-Api-Key: <key>

Request Payload:

{
  "data": [
    {
      "marker": "",
      "coords": [2517.14966, -25.38, 97.32],
      "heading": 85.0
    }
  ]
}

Success Response (200 OK):

{
  "success": true,
  "message": "Matrix signs reset",
  "activeMarkers": { ... }
}

---

Error Responses

Status Code	Reason	Example Response
401 Unauthorized	Missing or invalid API key	{"success": false, "status": 401, "error": "Unauthorized: Invalid or missing API key"}
400 Bad Request	Malformed JSON or missing data array	{"success": false, "error": "Missing payload data"}