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

Quickstart

Public banner endpoint

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

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).
`size`	string	Shortcut for supported sizes, e.g. `468x60`.
`format`	png\|webp	Image format. Default is png.
`data_mode`	manual\|query\|plugin	Defines the input strategy.

Example

curl request

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

<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" />

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.

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.