API

Alle Endpunkte liegen unter /api/v1. Antworten sind JSON, Zeitangaben in ISO 8601 (UTC), Zahlen ohne Tausendertrennzeichen.

Basisadresse

https://mcstats.de/api/v1

Authentifizierung

Jeder Aufruf braucht den Schlüssel deines Kontos – entweder als Header oder als Parameter.

curl -H "Authorization: Bearer DEIN_API_SCHLUESSEL" https://mcstats.de/api/v1/servers
curl "https://mcstats.de/api/v1/servers?key=DEIN_API_SCHLUESSEL"

API-Schlüssel

Jedes Konto bekommt einen Schlüssel. Du findest ihn in den Einstellungen.

Server

GET/api/v1/servers

Liste aller Server, seitenweise.

Parameter	Bedeutung	Standard
sort	Sortierung: players, trending, record, new	players
edition	java oder bedrock	–
category	Kategorie, siehe /meta	–
language	Sprache, siehe /meta	–
q	Suche in Name und Adresse	–
page	Seite, ab 1	1
limit	Anzahl je Seite, höchstens 200	50

GET/api/v1/servers/{id}

Ein einzelner Server mit allem, was wir über ihn wissen.

Verlauf

GET/api/v1/servers/{id}/history

Gemittelte Zeitreihe für Diagramme.

Parameter	Bedeutung	Standard
range	Zeitraum: 24h, 7d oder 30d	7d

GET/api/v1/servers/{id}/day

Wann auf dem Server etwas los ist, über den Tag verteilt.

Parameter	Bedeutung	Standard
range	Zeitraum: 24h, 7d oder 30d	7d

GET/api/v1/servers/{id}/pings

Einzelne Messungen, so wie sie gespeichert wurden.

Parameter	Bedeutung	Standard
limit	Anzahl der Einträge	100

Ranglisten

GET/api/v1/leaderboard

Fertige Rangliste, dieselbe wie auf der Website.

Parameter	Bedeutung	Standard
board	welche Rangliste: players, trending, record, uptime, new	players
limit	Anzahl der Einträge	25

GET/api/v1/totals

Alle Server zusammengezählt, plus aktuelle Summen.

Parameter	Bedeutung	Standard
range	Zeitraum: 24h, 7d oder 30d	7d
mode	Mittelwert oder Spitze: avg, peak	avg

Serverstatus

GET/api/v1/status

Beliebige Adresse sofort abfragen. Nichts davon wird gespeichert.

Parameter	Bedeutung	Standard
host	Adresse des Servers	Pflicht
edition	java oder bedrock	java
port	Port, sonst Standard je Edition	25565 / 19132

curl "https://mcstats.de/api/v1/status?host=mc.hypixel.net&key=DEIN_API_SCHLUESSEL"

Konto

GET/api/v1/me

Dein Konto und deine Server.

GET/api/v1/meta

Auswahllisten und Eckdaten, damit Clients keine Werte raten müssen.

Schreiben

Schreibende Aufrufe schicken JSON und brauchen den Schlüssel des Besitzers. Admins dürfen fremde Server ändern.

POST/api/v1/servers

Eigenen Server eintragen. Rumpf: host, dazu optional edition, port, name, website, categories, languages.

PATCH/api/v1/servers/{id}

Eigenen Server ändern: name, website, categories, languages.

DELETE/api/v1/servers/{id}

Eigenen Server samt Verlauf entfernen.

curl -X POST -H "Authorization: Bearer DEIN_API_SCHLUESSEL" \
  -H "content-type: application/json" \
  -d '{"host":"mc.example.com","edition":"java","categories":["smp"],"languages":["de"]}' \
  https://mcstats.de/api/v1/servers

Fehler

Code	Wann
400	Eingabe unbrauchbar, Feld error erklärt warum
401	Schlüssel fehlt oder ist ungültig
403	Kein Zugriff auf fremde Server
404	Server oder Konto gibt es nicht
429	Höchstens 20 Abfragen pro Minute je Konto beziehungsweise IP-Adresse.

{ "error": "unauthorized", "message": "API-Schlüssel fehlt oder ist ungültig." }

Grenzen

Höchstens 20 Abfragen pro Minute je Konto beziehungsweise IP-Adresse. /status
Private und lokale Adressen werden abgewiesen.
Bedrock wird über UDP gemessen; in Serverless-Umgebungen kann das fehlschlagen.
Ping alle 60 Sekunden