Endpoint Reference

EzBanners API endpoints

Detailed payloads, headers, and responses for each EzBanners API endpoint. Use this alongside the plugin documentation when building integrations or dashboards.

Back to API overview

Public

GET /api/banner

Public banner rendering with optional query or manual stats. No auth required.

            GET https://ezbanners.org/api/banner?server_name=EzBanners&online_players=42&max_players=100&template_key=minimal-status&size=468x60&theme=dark
        

Key parameters

data_mode: manual | query | plugin
server_name, online_players, max_players, motd_line_1, motd_line_2
template_key (template slug), theme, size, format

Use data_mode=query with ip_address to fetch live stats.

Plugin

POST /api/server/heartbeat

Lightweight keep-alive for server presence and version tracking.

            Headers:

            X-Server-UUID: <server uuid>

            X-Server-Token: <api token>

            X-Timestamp: <unix timestamp>

            X-Signature: HMAC_SHA256(timestamp + "." + rawBody, token)

            Payload:

            {

              "name": "Skyblock Realm",

              "plugin_version": "1.2.3",

              "status": "online"

            }

Legacy header X-Server-Id is still accepted for backwards compatibility.

Plugin

POST /api/server/update

Main sync endpoint for server stats consumed by banners.

            Headers:

            X-Server-UUID: <server uuid>

            X-Server-Token: <api token>

            X-Timestamp: <unix timestamp>

            X-Signature: HMAC_SHA256(timestamp + "." + rawBody, token)

            Payload:

            {

              "name": "Skyblock Realm",

              "plugin_version": "1.2.3",

              "status": "online",

              "stats": {

                "players": { "online": 42, "max": 150 },

                "tps": 19.8,

                "motd": "Welcome to EzBanners!",

                "version": "1.20.4"

              }

            }

            Response:

            { "message": "Server data updated." }

Plugin

GET /api/server/status

Returns the latest server status and stats cached by EzBanners.

            Headers:

            X-Server-UUID: <server uuid>

            X-Server-Token: <api token>

            X-Timestamp: <unix timestamp>

            X-Signature: HMAC_SHA256(timestamp + "." + rawBody, token)

            Response:

            {

              "uuid": "server-uuid",

              "name": "Skyblock Realm",

              "status": "online",

              "stats": { "players": { "online": 42, "max": 150 } }

            }

Plugin

POST /api/plugins/{plugin_uuid}/data

Send custom stats/meta for non-server banner templates.

            Headers:

            X-Plugin-Token: <plugin api token>

            X-Timestamp: <unix timestamp>

            X-Signature: HMAC_SHA256(timestamp + "." + rawBody, token)

            Payload:

            {

              "plugin": { "name": "EzAuction", "version": "1.2.0" },

              "stats": { "activeAuctions": 12, "totalSales": 3421 },

              "meta": { "status": "SALE LIVE" }

            }

            Response:

            { "message": "Plugin data updated." }