MarvinMC API Documentation

01 / Grundlagen

Schnellstart

Neue Integrationen verwenden die versionierte URL. Derselbe Endpoint ohne /v1 nutzt automatisch die aktuelle v1-Implementierung.

Basis-URL

https://marvinmc.dev/v1
/minecraft entspricht /v1/minecraft.

Antworten

JSON ist Standard. Einige Konverter liefern XML oder Bilddaten.

Fehler

HTTP-Status plus error.code, Nachricht und Request-ID.

curl "https://marvinmc.dev/v1/calculate?q=sqrt(144)%2B6"

{
  "expression": "sqrt(144)+6",
  "result": "18"
}

Fehlerformat: {"error":{"code":"...","message":"...","request_id":"..."}}. Die Request-ID gehört in Fehlermeldungen an den Betreiber.

02 / Ausprobieren

Live-Konsole

Die Konsole sendet nur sichere GET-Anfragen. Schreibende Endpoints testest du mit den dokumentierten cURL-Beispielen.

Bereit. Wähle einen Endpoint und sende die Anfrage.

03 / Endpoints

Basisdienste

Kleine, zustandslose Helfer für IP-Adressen, Berechnungen, Zufallswerte und Zeitkonvertierung.

GET/v1/ipJSON

Gibt die direkte Client-IP zurück. Weitergeleitete Header werden nur von konfigurierten, vertrauenswürdigen Proxies akzeptiert.

Keine Parameter.

{ "ip": "203.0.113.42" }

GET/v1/calculateJSON

Wertet einen begrenzten mathematischen Ausdruck ohne eval() aus. Unterstützt + - * / % ^, Klammern, pi, e und Funktionen wie sqrt, sin, log oder round.

Parameter	Typ	Beschreibung
q	string	Ausdruck, maximal 512 Zeichen

curl "https://marvinmc.dev/v1/calculate?q=(5%2B5)*2"

{"expression":"(5+5)*2","result":"20"}

GET/v1/randomJSON

Parameter	Default	Beschreibung
length	16	1 bis 256 Zeichen
lowercase	true	Kleinbuchstaben
uppercase	true	Großbuchstaben
numbers	true	Ziffern
special	false	Sonderzeichen
custom	-	Zusätzliche druckbare Zeichen

GET /v1/random?length=24&special=true

{
  "value": "7D...sicher-generiert...",
  "length": 24
}

GET/v1/timeJSON

Konvertiert entweder date nach Unix oder unix in ein Datum. Ohne beide Werte wird die aktuelle Zeit verwendet.

Parameter	Beispiel	Beschreibung
date	2026-07-03 16:00	Datum oder `now`
unix	1783087200	Timestamp oder `now`
zone	Europe/Berlin	IANA-Zeitzone, Default UTC
format	c	PHP-Date-Format für Unix-Eingaben

GET /v1/time?unix=now&zone=Europe%2FBerlin&format=c

{
  "timezone": "Europe/Berlin",
  "date": "2026-07-03T...+02:00",
  "unix": 1783...
}

04 / Daten

Daten & Dateien

Konvertierung und Abfragen mit festen Größenlimits. Remote-URL-Imports wurden entfernt, um SSRF zu verhindern.

POST/v1/convert/xml-to-jsonJSON

XML bis 1 MB im Body. DTD- und Entity-Deklarationen sind gesperrt.

curl -X POST \
  -H "Content-Type: application/xml" \
  --data '<user id="7"><name>Marvin</name></user>' \
  https://marvinmc.dev/v1/convert/xml-to-json

{
  "root": "user",
  "data": {
    "@attributes": {"id": "7"},
    "name": "Marvin"
  }
}

POST/v1/convert/json-to-xmlXML

JSON bis 1 MB im Body. Der optionale Parameter root setzt das XML-Wurzelelement.

curl -X POST \
  -H "Content-Type: application/json" \
  --data '{"name":"Marvin","active":true}' \
  "https://marvinmc.dev/v1/convert/json-to-xml?root=user"

<?xml version="1.0" encoding="UTF-8"?>
<user>
  <name>Marvin</name>
  <active>true</active>
</user>

POST/v1/base64-imageIMAGE

Dekodiert PNG, JPEG, GIF oder WebP bis 5 MB. Das Bild wird vollständig validiert und neu kodiert, statt als ausführbare Datei gespeichert zu werden.

Body: Data-URI oder JSON mit Feld data.

curl -X POST \
  --data-binary @image-data-uri.txt \
  -o clean-image.png \
  https://marvinmc.dev/v1/base64-image

GET/v1/minecraftJSON / XML

Fragt den Status eines öffentlichen Java-Servers mit drei Sekunden Timeout ab. Private/reservierte Ziele und Ports unter 1024 sind blockiert. SRV-Records werden unterstützt.

server	string	Host oder `host:port`
format	json/xml	Optionales Ausgabeformat

curl "https://marvinmc.dev/v1/minecraft?server=example.org:25565"

GET/v1/whoisJSON

Liest GeoIP-, Zeitzonen- und ASN-Daten ausschließlich aus der lokalen GeoLite2-Datenbank. Ohne Parameter wird die Client-IP verwendet.

ip

IPv4 / IPv6

Optional

{
  "ip": "1.1.1.1",
  "country_code": "AU",
  "timezone": {"id": "Australia/Sydney"},
  "connection": {"asn": 13335}
}

05 / Bilder

QR-Code

Erzeugt valide QR-Codes direkt als PNG oder SVG. Die Vorschau nutzt denselben öffentlichen Endpoint wie deine Integration.

GET/v1/qr-codePNG / SVG

Für kurze URLs reicht GET. POST akzeptiert ein JSON-Objekt mit denselben Parametern oder reinen UTF-8-Text im Body. Der unversionierte Alias /qr-code verwendet ebenfalls v1.

PNG · 352 × 352 px · medium

Parameter

Parameter	Default	Beschreibung
content	-	Pflichtfeld, UTF-8-Text mit maximal 1024 Bytes
format	png	`png` oder `svg`
size	512	QR-Matrix von 128 bis 2048 Pixeln; der Rand kommt außen hinzu
margin	16	Rand pro Seite von 0 bis 128 Pixeln
error_correction	medium	`low`, `medium`, `quartile` oder `high`
foreground	#101114	Sechsstellige Hex-Farbe
background	#ffffff	Sechsstellige Hex-Farbe; Kontrast mindestens 3:1
download	false	Mit `true` als Dateianhang ausliefern

curl "https://marvinmc.dev/v1/qr-code?content=Hallo&format=png&size=512" \
  --output qr-code.png

curl -X POST \
  -H "Content-Type: application/json" \
  --data '{"content":"Hallo","format":"svg"}' \
  https://marvinmc.dev/v1/qr-code \
  --output qr-code.svg

Responses: 200 liefert direkt image/png oder image/svg+xml. Ungültige Werte liefern JSON mit 400, 413 oder 422.

06 / Schutz

CAPTCHA

Einmalig nutzbare Bild-CAPTCHAs mit kurzer Lebensdauer und optionaler Bindung an ein serverseitiges Geheimnis.

GET/v1/captchaJSON

Erstellt ein sechsstelliges CAPTCHA mit PNG- und WebP-Bild. validity liegt zwischen 1 und 600 Sekunden, Default 120. Ein optionaler Signature-Header bindet Erstellung und Prüfung an dasselbe Geheimnis.

curl -H "Signature: server-secret" \
  "https://marvinmc.dev/v1/captcha?validity=180"

{
  "images": {
    "png": "https://marvinmc.dev/captcha/images/...png",
    "webp": "https://marvinmc.dev/captcha/images/...webp"
  },
  "id": "...",
  "expire": 1783...
}

POST/v1/captcha/verifyJSON

Parameter	Pflicht	Beschreibung
id	ja	ID aus der Erstellung
code	ja	Code aus dem Bild

curl -X POST -H "Signature: server-secret" \
  "https://marvinmc.dev/v1/captcha/verify?id=ID&code=123456"

{"solved":true}

07 / Dokumente

PDF

Wandelt begrenztes, bereinigtes HTML in ein abrufbares PDF um, ohne externe Inhalte nachzuladen.

POST/v1/pdfJSON

Erzeugt ein PDF aus maximal 500 KB HTML. Skripte, Formulare, eingebettete Objekte und externe Bilder werden entfernt. Bilder sind nur als Base64-Data-URI erlaubt.

Parameter	Default	Beschreibung
title	unnamed	Titel und Dateiname
author	MarvinMC.dev	PDF-Metadaten
tags	-	Schlüsselwörter
topic	-	Betreff

curl -X POST \
  -H "Content-Type: text/html" \
  --data '<h1>Report</h1><p>Sicheres HTML</p>' \
  "https://marvinmc.dev/v1/pdf?title=Report"

{
  "id": "aB3...",
  "file": "Report.pdf",
  "path": {
    "view": "/pdf/view/aB3.../Report.pdf",
    "download": "/pdf/download/aB3.../Report.pdf"
  }
}

08 / Integrierte Dokumentation

MarvinLobby API

Persistente JSON-Daten pro Datenbank-ID. Globale Werte und Spielerwerte sind getrennt; Dot-Notation bildet verschachtelte Keys ab.

Base URL: /v1/marvinlobby. /marvinlobby ist ein Alias derselben v1-Implementierung. Secrets gehören in Authorization: Bearer ... oder X-API-Key, nicht in URLs.

Registrieren

register ist die einzige Aktion ohne ID. Neue Secrets benötigen 8 bis 256 Zeichen und werden mit Argon2id gespeichert.

action	register	Pflicht
secret	string	Alternativ X-API-Key
licenseOwner	string	Optional mit licenseId
licenseId	string	Optional mit licenseOwner

curl -X POST \
  -H "X-API-Key: sehr-langes-secret" \
  -d "action=register" \
  https://marvinmc.dev/v1/marvinlobby

{"status":"ok","id":12}

Aktionen

set
Wert setzen oder überschreiben.

add
Zahl addieren, Text anhängen oder Liste erweitern.

remove
Zahl reduzieren oder Listenwert entfernen.

reset
Einen Key entfernen.

get / getAll
Wert oder kompletten Scope lesen.

deleteAll
Kompletten Scope entfernen.

listUuids
Vorhandene Scopes auflisten.

leaderboard
Numerischen Stat-Key sortieren.

register
Neue Datenbank-ID anlegen.

Daten schreiben

Parameter	Beschreibung
action	`set`, `add`, `remove` oder `reset`
id	Datenbank-ID
uuid	Spieler-UUID oder `global`
key	Dot-Key, z. B. `economy.coins`
value	Typisierter JSON-Wert, außer bei reset

curl -X POST \
  -H "Authorization: Bearer sehr-langes-secret" \
  -d "action=add" -d "id=12" \
  -d "uuid=069a79f4-44e9-4726-a5be-fca90e38aaf5" \
  -d "key=economy.coins" -d "value=25" \
  https://marvinmc.dev/v1/marvinlobby

Leaderboard

Parameter: stat ist Pflicht, limit liegt zwischen 1 und 100, reverse=1 sortiert absteigend. positionOf sucht die Position einer UUID, place liefert einen bestimmten Rang.

curl -X POST \
  -H "X-API-Key: sehr-langes-secret" \
  -d "action=leaderboard" -d "id=12" \
  -d "stat=woolbattle.wins" -d "reverse=1" -d "limit=5" \
  https://marvinmc.dev/v1/marvinlobby

Period-Keys

Abgelaufene Perioden werden beim Zugriff bereinigt: wins@D2026-07-03 für Tag, wins@W2026-W27 für ISO-Woche, wins@M2026-07 für Monat und wins@Y2026 für Jahr.

09 / Integration

MC-Linker

Verknüpft Discord-Nutzer mit Minecraft-Profilen, bewertet deren Vertrauensstufe und synchronisiert Discord-Rollen.

01

Token anfordern

Der Nutzer startet in Discord /link oder klickt den Link-Button.

02

In Minecraft bestätigen

Der persönliche Befehl /link <token> wird auf einem angebundenen Server ausgeführt.

03

Verknüpfen & synchronisieren

Der Server bestätigt signiert das Profil; Linker und Rollen-Queue übernehmen den Rest.

Eigenständige Integration: Der MC-Linker läuft bewusst unter /marvinlobby/mclinker/ und nicht unter /v1. Ohne Lookup-Parameter führt die URL zurück zu diesem Dokumentationsabschnitt.

Öffentliche Profilabfrage

GET/marvinlobby/mclinker/JSON

Löst eine Discord-ID oder Minecraft-UUID auf und liefert nur Profile, die der gewählten Verifikationsstufe entsprechen. Werden beide IDs angegeben, müssen sie zur selben Verknüpfung gehören.

Parameter	Pflicht	Beschreibung
discord_id	alternativ	Discord-Snowflake
minecraft_uuid	alternativ	UUID mit oder ohne Bindestriche
verificationstep	nein	Stufe 1 bis 4, Default 2
key	nein	Guild-ID oder KID zur Erkennung eigener Server-Links

curl "https://marvinmc.dev/marvinlobby/mclinker/?discord_id=123456789012345678&verificationstep=2"

Verifikationsstufen

1	Alle sichtbaren Links
2	Eigener Server, Partner und verifiziert
3	Eigener Server und verifiziert
4	Nur vollständig verifiziert

{
  "discord": "123456789012345678",
  "minecraft": "11111111-2222-3333-4444-555555555555",
  "profiles": [{
    "name": "ExamplePlayer",
    "verification": 4,
    "verificationText": "verified",
    "uuid": "11111111-2222-3333-4444-555555555555"
  }],
  "everywhereProfiles": []
}

Responses200 Treffer 400 ungültige Eingabe 404 nicht gefunden 409 IDs widersprechen sich

Signierte Partner-Anfragen

Server erhalten über Discord /setup eine Guild-ID, KID und einen privaten Ed25519-Schlüssel. Der private Schlüssel wird nur einmal ausgegeben und vom Linker nicht gespeichert.

Header	Wert
X-Partner-Id	Discord-Guild-ID aus `/setup`
X-Key-Id	Aktuelle KID der Guild
X-Signature-Timestamp	Aktueller Unix-Timestamp, maximal ±300 Sekunden
X-Signature-Ed25519	Hex-kodierte Signatur

message = utf8(timestamp) + raw_request_body
signature = ed25519_sign(private_key, message)

POST/marvinlobby/mclinker/?action=verify204

Bestätigt den persönlichen Link-Token und ordnet das Minecraft-Profil dem Discord-Nutzer zu. Die Vertrauensstufe ergibt sich aus der KID des signierenden Servers.

Erfolgreich: 204 No Content.

{
  "token": "PERSONAL_LINK_TOKEN",
  "profile": {
    "uuid": "11111111-2222-3333-4444-555555555555",
    "name": "ExamplePlayer"
  }
}

POST/marvinlobby/mclinker/?action=sync_roles204

Schreibt Rollenänderungen priorisiert in die Queue. Empfohlen ist der Rank-Modus: Der Server sendet den Rank, der Linker löst die in Discord konfigurierte Rolle auf.

Rank-Modus

{
  "uuid": "11111111-2222-3333-4444-555555555555",
  "rank": "vip",
  "level": 2,
  "priority": 2,
  "require_main_profile": true
}

Direkte Rollenänderung

{
  "uuid": "11111111-2222-3333-4444-555555555555",
  "role": "123456789012345678",
  "action": "add",
  "level": 2
}

Discord-Befehle

/linkPersönlichen Link-Token anfordern

/mainHauptprofil auswählen

/infoVerknüpfte Profile anzeigen

/linkmessageLink-Button im Channel posten

/setupServer-Schlüsselpaar erzeugen oder rotieren

/verificationStufe, Standardrolle und Sync verwalten

/authorizeAutorisierte Administratoren verwalten

/ranksyncMinecraft-Ranks Discord-Rollen zuordnen

Schlüssel schützenDer private Ed25519-Schlüssel gehört ausschließlich in die Server-Konfiguration. Niemals in URLs, Logs, Discord-Nachrichten oder Client-Code schreiben. Ein erneutes /setup rotiert das Schlüsselpaar.

10 / Migration

Alte URLs

Bestehende Integrationen funktionieren weiter. Neue Projekte sollten ausschließlich die v1-Routen verwenden.

Alt	Neu	Hinweis
`/ip/json`	`/v1/ip`	JSON bleibt gleich
`/calc/json`	`/v1/calculate`	`q` statt nacktem Query empfohlen
`/random`	`/v1/random`	Neu mit `random_int()`
`/time`	`/v1/time`	Validierte Zeitzonen
`/minecraft/json`	`/v1/minecraft`	Private Ziele blockiert
`/whois/json`	`/v1/whois`	Keine externen WHOIS-Aufrufe
`/captcha/json`	`/v1/captcha`	TTL maximal 600 Sekunden
`/pdf/create/json`	`/v1/pdf`	Nur bereinigtes HTML

11 / Anwendungen

Eigenständige Projekte

Diese Bereiche sind keine Utility-API und werden deshalb nicht durch den zentralen API-Controller geschleust.

Eine API.
Klare Wege.