Bridge API Reference

The Node.js Bridge Server (roblox-bridge-file/) acts as the secure middleman between your local Python application and your live Roblox game servers.

Roblox experiences cannot receive incoming HTTP POST requests. Therefore, to achieve DataStore Sync, the Python app pushes data to this Bridge Server, and the Roblox Lua module regularly polls this server for updates.

1. Authentication

The bridge is secured via a shared secret password.

Both the POST and GET requests require the x-bridge-secret header. Any request that lacks this header, or provides a secret that does not exactly match the server's configured environment variable, will be immediately rejected with a 401 Unauthorized status.

Secret Mismatch: The Bridge Secret you configure in the Python App's Configuration panel must match the server's exact secret. A mismatch will cause a sync failure at the end of an upload batch. If this happens, you can fix the secret in the app and click the "Retry Bridge Sync" button to resend the payload.

2. API Endpoints

The POST Endpoint

Direction: Python App → Bridge Server Purpose: Receives newly approved audio batch metadata.

Headers: x-bridge-secret: <your_secret>
Body Format: A JSON array of track objects (containing fields like AudioId, Title, Duration, Category, etc.)
Behavior: The server accepts the payload, replaces its current stored data (in-memory or in Redis, depending on your setup), and updates an internal timestamp.
Success Response: 200 OK

The GET Endpoint

Direction: Roblox Lua Module → Bridge Server Purpose: Allows the live game to poll for new music data.

Headers: x-bridge-secret: <your_secret>
Behavior: Retrieves the currently stored data block.
Success Response: 200 OK
Response Format:
```
{
  "payload": [ ... array of track objects ... ],
  "timestamp": 1714567890123 
}
```
(Note: The timestamp is a Unix millisecond timestamp indicating when the payload was last updated. The Lua module uses this to avoid re-processing identical payloads).

3. Running the Bridge Locally

If you are developing or testing, you can run the bridge server locally:

Open a terminal at the repository root (where the package.json lives).
Install dependencies:
```
npm install
```
Start the server:
```
node roblox-bridge-file/index.js
```

By default, the server will listen on port 3000 (e.g., http://localhost:3000).

4. Deployment

For the live Roblox game to access the bridge, it must be deployed to a public web host.

Because it is a standard Express application, it can be deployed to virtually any Node.js hosting provider, such as Render, Heroku, DigitalOcean, or Vercel.

Once deployed, copy the public URL (e.g., https://my-audio-bridge.onrender.com) and paste it into the Bridge Server URL field in the Python app's Configuration panel.

Production Security: You must deploy the bridge behind an HTTPS/SSL connection in production. If you use standard HTTP, your x-bridge-secret header will be transmitted in plaintext across the internet, exposing your bridge server to unauthorized access.