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.
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. For a practical overview aimed at Spigot, Hangar, Modrinth, and GitHub publishing workflows, see the Minecraft Plugin Badges landing page.
Endpoint Pattern
GET https://ezbanners.org/shields/plugins/{plugin-uuid}/{metric}.png
Available Metrics
| Metric | Description | Example URL |
|---|---|---|
version |
Plugin version number | /shields/plugins/{uuid}/version.png |
downloads |
Total downloads from all sources (formatted with k/M suffixes) | /shields/plugins/{uuid}/downloads.png |
rating |
Plugin rating from Spigot or other sources | /shields/plugins/{uuid}/rating.png |
status |
Active/inactive status (based on last seen within 24 hours) | /shields/plugins/{uuid}/status.png |
minecraft-versions |
Compatibility summary from minecraft_versions, using a compact range such as 1.20-1.21 |
/shields/plugins/{uuid}/minecraft-versions.png |
server-software |
Compatibility summary from server_software, using compact labels such as Paper/Folia or Paper/Folia+2 |
/shields/plugins/{uuid}/server-software.png |
spigot |
Spigot resource ID | /shields/plugins/{uuid}/spigot.png |
github |
GitHub repository name | /shields/plugins/{uuid}/github.png |
modrinth |
Modrinth project ID | /shields/plugins/{uuid}/modrinth.png |
hangar |
Hangar project slug | /shields/plugins/{uuid}/hangar.png |
spigot-downloads |
Spigot downloads from meta.spigot.downloads with an orange spigot dl label |
/shields/plugins/{uuid}/spigot-downloads.png |
modrinth-downloads |
Modrinth downloads from meta.modrinth.downloads with a green modrinth dl label |
/shields/plugins/{uuid}/modrinth-downloads.png |
modrinth-followers |
Modrinth followers from meta.modrinth.followers with a green followers label |
/shields/plugins/{uuid}/modrinth-followers.png |
hangar-downloads |
Hangar downloads from meta.hangar.downloads with a blue hangar dl label |
/shields/plugins/{uuid}/hangar-downloads.png |
hangar-stars |
Hangar stars from meta.hangar.stars with a blue stars label |
/shields/plugins/{uuid}/hangar-stars.png |
hangar-watchers |
Hangar watchers from meta.hangar.watchers with a blue watchers label |
/shields/plugins/{uuid}/hangar-watchers.png |
spigot-version |
Spigot latest version from meta.spigot.latest_version with the native spigot label and an N/A fallback |
/shields/plugins/{uuid}/spigot-version.png |
modrinth-version |
Modrinth latest version from meta.modrinth.latest_version with the native modrinth label and an N/A fallback |
/shields/plugins/{uuid}/modrinth-version.png |
hangar-version |
Hangar latest version from meta.hangar.latest_version with the native hangar label and an N/A fallback |
/shields/plugins/{uuid}/hangar-version.png |
github-release |
GitHub latest release from meta.github.latest_release with the native release label and an N/A fallback |
/shields/plugins/{uuid}/github-release.png |
github-stars |
GitHub stars from meta.github.stars with a compact formatNumber() value and an N/A fallback |
/shields/plugins/{uuid}/github-stars.png |
github-forks |
GitHub forks from meta.github.forks with a compact formatNumber() value and an N/A fallback |
/shields/plugins/{uuid}/github-forks.png |
github-watchers |
GitHub watchers from meta.github.watchers with a compact formatNumber() value and an N/A fallback |
/shields/plugins/{uuid}/github-watchers.png |
github-issues |
Open GitHub issues counted from the size of the meta.github.open_issues array, using healthier green tones for lower counts and a warning yellow when the count is high |
/shields/plugins/{uuid}/github-issues.png |
license |
Normalized license badge sourced from meta.hangar.license first, then fallback repository metadata such as GitHub license fields, producing short badge-safe values like MIT, GPL-3.0, or Custom |
/shields/plugins/{uuid}/license.png |
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.)
# 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">
# Topic page compatibility strip
[IMG]https://ezbanners.org/shields/plugins/YOUR-UUID/minecraft-versions.png[/IMG] [IMG]https://ezbanners.org/shields/plugins/YOUR-UUID/server-software.png[/IMG]
Embedding on Topic Pages
Use the compatibility shields together near the top of a support thread, resource overview, or changelog topic so readers can immediately see supported Minecraft versions and server platforms.
Topic Page Embed Examples
# Forum/BBCode topic header
[center][IMG]https://ezbanners.org/shields/plugins/YOUR-UUID/minecraft-versions.png[/IMG]
[IMG]https://ezbanners.org/shields/plugins/YOUR-UUID/server-software.png[/IMG][/center]
# HTML for docs, wiki, or announcement pages
<div class="plugin-compat">
<img src="https://ezbanners.org/shields/plugins/YOUR-UUID/minecraft-versions.png" alt="Supported Minecraft versions">
<img src="https://ezbanners.org/shields/plugins/YOUR-UUID/server-software.png" alt="Supported server software">
</div>
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
# Minecraft compatibility summary
GET https://ezbanners.org/shields/plugins/YOUR-UUID/minecraft-versions.png
# Server software compatibility summary
GET https://ezbanners.org/shields/plugins/YOUR-UUID/server-software.png
# Spigot downloads
GET https://ezbanners.org/shields/plugins/YOUR-UUID/spigot-downloads.png
# Modrinth downloads
GET https://ezbanners.org/shields/plugins/YOUR-UUID/modrinth-downloads.png
# Modrinth followers
GET https://ezbanners.org/shields/plugins/YOUR-UUID/modrinth-followers.png
# Hangar downloads
GET https://ezbanners.org/shields/plugins/YOUR-UUID/hangar-downloads.png
# Hangar stars
GET https://ezbanners.org/shields/plugins/YOUR-UUID/hangar-stars.png
# Hangar watchers
GET https://ezbanners.org/shields/plugins/YOUR-UUID/hangar-watchers.png
# GitHub stars
GET https://ezbanners.org/shields/plugins/YOUR-UUID/github-stars.png
# GitHub forks
GET https://ezbanners.org/shields/plugins/YOUR-UUID/github-forks.png
# GitHub watchers
GET https://ezbanners.org/shields/plugins/YOUR-UUID/github-watchers.png
# GitHub open issues
GET https://ezbanners.org/shields/plugins/YOUR-UUID/github-issues.png
# License badge
GET https://ezbanners.org/shields/plugins/YOUR-UUID/license.png
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.