EzBanners Public API

Use EzBanners without installing a plugin.

Generate dynamic Minecraft server banners directly from query parameters. The public API supports manual data, optional server query lookups, and plugin-based workflows when you are ready to upgrade.

Get started Create account for advanced templates Java Plugin API Docs

Quickstart

Public banner endpoint

No authentication required for default usage. Add parameters to control the content.

                    Example Request
                

GET https://ezbanners.org/api/banner?server_name=EzBanners&online_players=42&max_players=100&motd_line_1=Welcome%20back&motd_line_2=Powered%20by%20EzBanners&template_key=minimal-status&theme=dark&width=468&height=60

Authentication

Open access (rate limited)

The endpoint is public and rate limited per IP. Upgrade to dashboard templates for private assets and premium layouts.

Rate limit: 120 requests / minute / IP. Cached responses are served when available.

Data Modes

Choose how banner data is supplied

Mode	Description	Best for
manual	Pass everything through query parameters. Default mode.	WERM or any site that already knows the server data.
query	Optional PHP-based server query (requires query enabled on the server).	Platforms that can provide an IP but no stats.
plugin	Reserved for EzBanners plugin integrations and signed requests.	Advanced dashboards, premium templates, analytics.

Set data_mode=query to enable the optional query lookup. Manual values always override query results.

Parameters

Supported query parameters

Parameter	Type	Notes
`server_name`	string	Displayed server name.
`ip_address`	string	Required for `data_mode=query`. Supports `host:port`.
`online_players`	int	Optional manual override.
`max_players`	int	Optional manual override.
`server_status`	online\|offline	Overrides banner status.
`motd_line_1`	string	Primary MOTD line.
`motd_line_2`	string	Secondary MOTD line.
`template_key`	string	Template slug (defaults to EzBanners minimal status template).
`theme`	light\|dark	Optional theme palette.
`width` / `height`	int	Matches supported sizes (468x60, 728x90, 300x250, 1200x300).
`size`	string	Shortcut for supported sizes, e.g. `468x60`, `1200x300`.
`format`	png\|webp	Image format. Default is png.
`data_mode`	manual\|query\|plugin	Defines the input strategy.

Example

curl request

                    cURL Example
                

curl "https://ezbanners.org/api/banner?server_name=WERM%20Hub&online_players=128&max_players=500&motd_line_1=Welcome%20to%20WERM&motd_line_2=Play%20today&template_key=minimal-status&theme=dark" --output banner.png

Example

Browser usage

                                        Plain HTML
                

<img src="https://ezbanners.org/api/banner?server_name=EzBanners&online_players=42&max_players=100&motd_line_1=Instant%20banner&motd_line_2=No%20plugin&theme=light" alt="EzBanners banner" />

                                        React Example
                                

export default function Banner() {
    return (
        <img
            src="https://ezbanners.org/api/banner?server_name=EzBanners&online_players=42&max_players=100&motd_line_1=Instant%20banner&motd_line_2=No%20plugin&theme=light"
            alt="EzBanners banner"
            width={468}
            height={60}
        />
    );
}

Optional Server Query

Enable query mode (optional)

EzBanners can fetch live stats from Minecraft servers using a PHP-based query library. This is optional and only used when data_mode=query is supplied.

                Query Mode Example
            

GET https://ezbanners.org/api/banner?data_mode=query&ip_address=play.example.com:25565&server_name=Example%20Server

If query is disabled or fails, the banner still renders using defaults or any manual overrides.

Plugin Shields

Shield/badge endpoints for plugin metrics

EzBanners provides shield-style badges (similar to shields.io) for plugin metrics. These are small, cacheable PNG badges perfect for embedding in documentation, forums, or GitHub READMEs.

Endpoint Pattern

GET https://ezbanners.org/shields/plugins/{plugin-uuid}/{metric}.png

Available Metrics

Metric	Description
`version`	Plugin version number
`downloads`	Total downloads from all sources (formatted with k/M suffixes)
`rating`	Plugin rating from Spigot or other sources
`status`	Active/inactive status (based on last seen within 24 hours)
`spigot`	Spigot resource ID
`github`	GitHub repository name
`modrinth`	Modrinth project ID
`hangar`	Hangar project slug

Query Parameters (Optional)

Parameter	Type	Notes
`label`	string	Override the left label text
`color`	hex color	Override badge color (without # prefix, e.g., `?color=4c1` or `?color=ff5733`)
`style`	flat\|flat-square\|plastic\|for-the-badge	Badge style (default: flat)

Examples

                Basic Usage
            

# Markdown (GitHub, GitLab, etc.)
![Version](https://ezbanners.org/shields/plugins/YOUR-UUID/version.png)
![Downloads](https://ezbanners.org/shields/plugins/YOUR-UUID/downloads.png)

# BBCode (SpigotMC, Bukkit forums, etc.)
[IMG]https://ezbanners.org/shields/plugins/YOUR-UUID/version.png[/IMG]

# HTML
<img src="https://ezbanners.org/shields/plugins/YOUR-UUID/version.png" alt="Version">

                Custom Colors and Labels
            

# Green downloads badge
GET https://ezbanners.org/shields/plugins/YOUR-UUID/downloads.png?color=4c1

# Custom label
GET https://ezbanners.org/shields/plugins/YOUR-UUID/version.png?label=latest%20version

# Red status indicator
GET https://ezbanners.org/shields/plugins/YOUR-UUID/status.png?color=e74c3c

Rate Limiting & Caching: Shield endpoints use the same rate limiting as banner images (120 requests/minute/IP). Responses are cached for 45 seconds and include appropriate cache headers.