REST APINo API keyCORSJSON · PNG · HTML

MCAPI.TR Developer Platform

API Documentation

The complete MCAPI.TR developer guide for querying Minecraft Java, Legacy and Bedrock servers and using icons, banners, widgets, trends and platform statistics.

OpenAPI JSON Try it live

Base URLhttps://mcapi.tr/api/v1

01 — Quick start

Get your first response in seconds

No setup or keys. Pick a client, copy the example and run it.

curl

curl "https://mcapi.tr/api/v1/status/mc.hypixel.net"

02 — API Playground

Send a live request from your browser

The request goes directly to the MCAPI.TR API and the formatted response appears below.

03 — Endpoint Reference

All public endpoints

Open a card for parameters, caching behavior and runnable examples.

GET/api/v1/status

API health check

Verifies service availability, version and server time. A lightweight endpoint for uptime monitors.

application/json

Authentication

No API key required

Cache

None

Content-Type

application/json

Example request

bash

curl "https://mcapi.tr/api/v1/status"

Example response

json

{
  "status": "OK",
  "timestamp": "2026-09-08T20:12:00.000Z",
  "service": "mcapi.tr-engine",
  "version": "0.1.0"
}

GET/api/v1/status/:address

Minecraft server status

Returns Java, Legacy Java or Bedrock availability with player, version, MOTD, favicon and latency data.

application/json

Authentication

No API key required

Cache

60 seconds by default

Content-Type

application/json

Parameters

Parameter	Location	Type	Default	Description
`address`*	path	string	—	Hostname or IP; an optional port may be appended: play.example.net:25565
`legacy`	query	boolean	false	Forces the pre-1.7.2 Java ping protocol.
`bedrock`	query	boolean	false	Uses the Bedrock Edition query; the default port becomes 19132.

Example request

bash

curl "https://mcapi.tr/api/v1/status/mc.hypixel.net"
curl "https://mcapi.tr/api/v1/status/bedrock.example.net:19132?bedrock=true"

Example response

json

{
  "query": {
    "host": "mc.hypixel.net",
    "port": 25565,
    "legacy": false,
    "bedrock": false
  },
  "server_id": "f17d4f75-...",
  "ip_address": "209.222.115.11",
  "icmp": true,
  "online": true,
  "stale": false,
  "error": null,
  "checked_at": "2026-09-12T15:59:36.430Z",
  "version": { "name": "Requires MC 1.8 / 1.21", "protocol": 47 },
  "players": { "online": 52184, "max": 200000, "sample": [] },
  "motd": {
    "raw": "§aHypixel Network",
    "clean": "Hypixel Network",
    "html": "<span style=\"color:#55FF55\">Hypixel Network</span>",
    "raw_lines": ["§aHypixel Network"],
    "clean_lines": ["Hypixel Network"]
  },
  "favicon": "data:image/png;base64,...",
  "srvRecord": null,
  "roundTripLatency": 18
}

GET/api/v1/trends

Trending servers

Returns servers ranked by trend score with cursor-based pagination metadata.

application/json

Authentication

No API key required

Cache

5 min

Content-Type

application/json

Parameters

Parameter	Location	Type	Default	Description
`limit`	query	integer	10	Page size, clamped between 1 and 50.
`cursor`	query	UUID	—	The meta.nextCursor value from the previous response.

Example request

bash

curl "https://mcapi.tr/api/v1/trends?limit=10"

Example response

json

{
  "success": true,
  "data": [
    {
      "server_id": "f17d4f75-...",
      "hostname": "mc.hypixel.net",
      "address": "mc.hypixel.net",
      "port": 25565,
      "edition": "java",
      "trend_score": 842,
      "daily_growth": 14.6,
      "is_online": true,
      "stale": false,
      "checked_at": "2026-09-12T15:59:36.430Z",
      "players_online": 52184,
      "players_max": 200000,
      "version": "Requires MC 1.8 / 1.21",
      "favicon": "21aa8597...",
      "record_players": 74312,
      "uptime_percentage": 99.8
    }
  ],
  "meta": { "nextCursor": "f17d4f75-...", "hasNext": true, "limit": 10 }
}

GET/api/v1/stats

Global platform statistics

Provides totals for requests, checked servers, online rate, active players and recent checks.

application/json

Authentication

No API key required

Cache

60 sec

Content-Type

application/json

Example request

bash

curl "https://mcapi.tr/api/v1/stats"

Example response

json

{
  "totalRequests": 1284502,
  "apiRequests": 612340,
  "serverQueries": 672162,
  "totalChecks": 672162,
  "onlineServers": 428,
  "offlineServers": 91,
  "activePlayers": 184205,
  "recentChecks": [],
  "onlineRate": 82.5
}

GET/api/v1/icon/dynamic

Server icon

Returns a server favicon and falls back to the MCAPI.TR default image when unavailable.

image/png | image/webp

Authentication

No API key required

Cache

Browser 1 day, CDN 7 days

Content-Type

image/png | image/webp

Parameters

Parameter	Location	Type	Default	Description
`address`*	query	string	—	Server address. server is accepted as a backwards-compatible alias.
`size`	query	integer	80	WebP output size, between 16 and 256 pixels.
`format`	query	png \| webp	png	Produces an optimized square image when set to webp.

Example request

bash

curl "https://mcapi.tr/api/v1/icon/dynamic?address=mc.hypixel.net&size=128&format=webp" --output server.webp

GET/api/v1/icon/sharp

Rounded server icon

Produces a resized PNG server icon with rounded corners.

image/png

Authentication

No API key required

Cache

Browser 1 day, CDN 7 days

Content-Type

image/png

Parameters

Parameter	Location	Type	Default	Description
`address`*	query	string	—	Server hostname or IP address.
`size`	query	integer	128	Output size between 32 and 512 pixels.

Example request

bash

curl "https://mcapi.tr/api/v1/icon/sharp?address=mc.hypixel.net&size=256" --output icon.png

GET/api/v1/banner/:address

Server status banner

Builds a shareable PNG banner with server name, players, MOTD, ping and favicon.

image/png

Authentication

No API key required

Cache

Subject to server/CDN policy

Content-Type

image/png

Parameters

Parameter	Location	Type	Default	Description
`address`*	path	string	—	Server used to generate the banner.
`size`	query	small \| normal \| large	normal	Output dimensions: 400×130, 600×180 or 800×240.
`style`	query	modern \| classic	modern	Banner appearance.
`textColor`	query	hex color	#FFFFFF	Primary text color.
`accentColor`	query	hex color	#10B981	Player-count accent color.
`showFavicon / showMotd / showPing`	query	boolean	true	Toggles icon, MOTD and latency fields independently.
`borderRadius`	query	number	0.5	Corner-radius multiplier.

Example request

bash

curl "https://mcapi.tr/api/v1/banner/mc.hypixel.net?size=large&accentColor=%2310B981" --output banner.png

GET/api/v1/banner/motd

MOTD text banner

Converts Minecraft-formatted MOTD text into an 800×180 PNG without querying a server.

image/png

Authentication

No API key required

Cache

No application cache

Content-Type

image/png

Parameters

Parameter	Location	Type	Default	Description
`motd`*	query	string	—	MOTD text up to 300 characters.
`textColor`	query	hex color	#FFFFFF	Default text color.
`accentColor`	query	hex color	#10B981	Background accent color.

Example request

bash

curl "https://mcapi.tr/api/v1/banner/motd?motd=%C2%A7aWelcome" --output motd.png

GET/api/v1/widget/:size/:address

Embeddable HTML widget

Returns customizable live server-status HTML for websites and dashboards.

text/html

Authentication

No API key required

Cache

60 sec + stale-while-revalidate

Content-Type

text/html

Parameters

Parameter	Location	Type	Default	Description
`size`*	path	small \| normal \| large	—	Widget layout and default height.
`address`*	path	string	—	Server address; demo may be used for previewing.
`theme`	query	dark \| light	dark	Base color theme.
`showPlayers / showVersion / showMotd`	query	boolean	true	Toggles the main information fields independently.
`showLatency / showFavicon`	query	boolean	true	Controls ping and favicon visibility.
`showProtocol / showBorder`	query	boolean	false	Optionally displays protocol and border.
`bgColor / textColor`	query	hex color	—	Widget background and text colors.
`onlineColor / offlineColor`	query	hex color	#10b981 / #ef4444	Online and offline state colors.
`gradientBg / gradientFrom / gradientTo`	query	boolean / hex	false	Gradient background controls.
`statusIndicator`	query	dot \| text \| badge \| none	dot	Status indicator style.
`iconSize`	query	small \| medium \| large	medium	Favicon size.
`font`	query	Inter \| Roboto \| Poppins \| Montserrat \| Outfit	—	Google Fonts family.
`textAlign`	query	left \| center \| right	left	Text alignment.
`customHeight`	query	CSS px	—	Custom height between 50 and 600 pixels.
`borderRadius / borderWidth`	query	number	0.75 / 1	Corner and border measurements.
`hoverEffect / glowEffect / boxShadow`	query	boolean	false	Enables visual effects.
`playerBarStyle`	query	default \| gradient \| striped \| animated	default	Player capacity bar appearance.

Example request

bash

curl "https://mcapi.tr/api/v1/widget/normal/mc.hypixel.net?theme=dark&showFavicon=true"

04 — Schema

Server response fields

Field	Type	Description
`query`	object	Resolved host, port and query mode.
`server_id`	UUID	Stable server identifier inside MCAPI.TR.
`online`	boolean	Whether the Minecraft ping completed successfully.
`stale`	boolean	Whether the response comes from the last known successful query rather than a fresh ping.
`checked_at`	ISO 8601	UTC timestamp of the server check represented by this response.
`icmp`	boolean	ICMP reachability result for the target IP.
`version`	object \| null	Server version label and protocol number.
`players`	object \| null	Online count, capacity and optional player sample.
`motd`	object \| null	Raw, clean and HTML MOTD forms plus line arrays.
`favicon`	data URL \| null	Base64-encoded server favicon.
`srvRecord`	object \| null	Resolved Minecraft SRV record details when discovery was used.
`roundTripLatency`	number \| null	Minecraft query latency in milliseconds.
`error`	string \| null	Safe error summary for a failed query.

HTTP

Status codes

200Request succeeded.

400Invalid address or query parameter.

404Server is offline or unreachable.

429Per-minute request limit exceeded.

500Unexpected server error.

503Maintenance mode is active.

Policies

Limits and caching

status:120 requests per minute per IP.
default:300 requests per minute by default for general endpoints.
media:Up to 5,000 requests per minute for icon, banner and widget endpoints.
cors:Public API endpoints allow all browser origins.
privacy:Request profiling does not retain raw IP addresses or user agents.

Official SDKs

Use the API in Node.js and Python

Official zero-dependency clients provide typed server queries, discovery, statistics and media helpers without requiring an API key.

Node.js

mcapitr

npm ↗

A Promise-based Node.js client with complete TypeScript declarations and Buffer helpers for generated media.

bash

npm install mcapitr

Node.js 18+TypeScriptPromise API

Python

mcapitr

PyPI ↗

Synchronous and asynchronous Python clients with typed exceptions, pagination and byte downloads.

bash

pip install mcapitr

Python 3.9+TypedSync + Async

Get your first response in seconds

Send a live request from your browser

All public endpoints

API health check

Example request

Example response

Minecraft server status

Parameters

Example request

Example response

Trending servers

Parameters

Example request

Example response

Global platform statistics

Example request

Example response

Server icon

Parameters

Example request

Rounded server icon

Parameters

Example request

Server status banner

Parameters

Example request

MOTD text banner

Parameters

Example request

Embeddable HTML widget

Parameters

Example request

Server response fields

Status codes

Limits and caching

Use the API in Node.js and Python

mcapitr

mcapitr

Privacy Policy

Protection of Your Personal Data

Collected Data

Cookies

Data Security

Contact

Terms of Use

Service Terms

Service Definition

Usage Limitations

Disclaimer

Intellectual Property Rights

Changes

Contact