Protector-API

Überblick

Die Protector-API ist eine REST-API, die in JSON antwortet. Alle Endpunkte liegen unter einer Basisadresse:

https://protector-bot.com/api/v1

Die API wird nur von protector-bot.com bereitgestellt. Sie gibt nie Zugriff auf die Maschinen, auf denen der Bot läuft.

Einen API-Schlüssel erhalten

1. Melde dich auf der Entwicklerseite mit Discord an.
2. Klicke auf Schlüssel erstellen und gib ihm einen Namen (zum Beispiel den Namen deines Bots).
3. Kopiere den Schlüssel sofort: Er beginnt mit pk_ und wird nur einmal angezeigt. Protector bewahrt nur einen Fingerabdruck davon auf.

Schlüssel verloren oder vermutest du ein Leck? Widerrufe ihn auf derselben Seite und erstelle einen neuen. Du kannst bis zu 5 aktive Schlüssel haben.

Der API-Pass erhöht jedes Limit und schaltet die Bildanalyse frei. Er wird im Shop von Protector auf Discord für 30 Tage gekauft und ist an dein Discord-Konto gebunden: Deine Schlüssel wechseln automatisch zu den Limits des API-Passes. Jeder neue Kauf fügt 30 Tage hinzu; 3 Tage vor dem Ende kommt eine Erinnerung per privater Nachricht. Ohne Pass funktionieren deine Schlüssel im kostenlosen Tarif weiter.

Authentifizierung

Sende deinen Schlüssel im Header Authorization jeder Anfrage:

Authorization: Bearer pk_dein_schluessel

Halte den Schlüssel geheim: Lege ihn nie in ein öffentliches Repository oder in Code, der im Browser eines Besuchers läuft.

Tarife und Limits

Die Monatszähler werden am ersten Tag jedes Monats (UTC) zurückgesetzt. Das Abfragen des Status eines Bildes (GET /image/{id}) und GET /me zählen nicht zum Monatskontingent, nur zum Minutenlimit.

Jede Antwort enthält diese Header:

Fehler

Ein Fehler liefert einen JSON-Body mit einem stabilen Code error und einer lesbaren message (auf Englisch):

{ "error": "rate_limited", "message": "Too many requests for this key. Wait before retrying.", "retry_after": 23 }

Endpunkte

GET /me

Dein Tarif, seine Limits und deine Nutzung in diesem Monat.

curl https://protector-bot.com/api/v1/me \
  -H "Authorization: Bearer pk_dein_schluessel"

{
  "plan": "pass",
  "limits": { "per_minute": 120, "per_month": 100000, "images_per_month": 3000 },
  "usage": { "month": "2026-10", "requests": 1834, "images": 41 },
  "key": { "name": "Mein Bot", "created_at": 1792150000 }
}

GET /blacklist/{user_id}

Sagt, ob ein Discord-Konto auf der Blacklist von Protector steht (Konten, die an Raids, Nukes oder Betrug beteiligt waren, vom Protector-Team bestätigt). Die Antwort ist nur true oder false: kein Grund, kein Beweis.

curl https://protector-bot.com/api/v1/blacklist/123456789012345678 \
  -H "Authorization: Bearer pk_dein_schluessel"

{ "user_id": "123456789012345678", "blacklisted": false }

Eine aufgeführte Person kann die Entscheidung auf der Einspruchsseite anfechten. Nutze diese Antwort nicht als alleinigen Grund, jemanden zu sanktionieren.

POST /link

Prüft einen Link: bekannte Betrugsdomains, Doppelgänger-Domains (kyrillische Buchstaben, Punycode, die wie „discord“ oder „steam“ aussehen) und Kurzlinks, die zu einem Betrug führen (der ersten Weiterleitung wird gefolgt).

curl https://protector-bot.com/api/v1/link \
  -H "Authorization: Bearer pk_dein_schluessel" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://dlscordnitro.com/gift"}'

{
  "url": "https://dlscordnitro.com/gift",
  "host": "dlscordnitro.com",
  "dangerous": true,
  "reason": "known_scam_domain",
  "matched": "dlscordnitro.com",
  "final_host": null
}

reason ist known_scam_domain, lookalike_domain, shortener_to_scam oder null. free_host: true wird hinzugefügt, wenn die Seite bei einem kostenlosen Hoster liegt, wo oft Fallen gebaut werden: an sich nicht gefährlich, aber einen genaueren Blick wert.

POST /text

Analysiert eine Nachricht so, wie Protector es auf Discord tut: explizite Wörter (auch mit Punkten, Leerzeichen oder Zahlen geschrieben, wie p.0.r.n), falsche Nitro-Geschenke und jeden enthaltenen Link. Der Text wird nicht gespeichert.

curl https://protector-bot.com/api/v1/text \
  -H "Authorization: Bearer pk_dein_schluessel" \
  -H "Content-Type: application/json" \
  -d '{"text": "free nitro for everyone https://dlscordnitro.com/gift"}'

{
  "nsfw": { "flagged": false, "term": null },
  "scam": { "flagged": true, "reason": "known_scam_domain" },
  "links": [
    { "url": "https://dlscordnitro.com/gift", "host": "dlscordnitro.com", "dangerous": true,
      "reason": "known_scam_domain", "matched": "dlscordnitro.com", "final_host": null }
  ]
}

Bis zu 20 Links werden pro Nachricht analysiert. scam.reason ist der Grund des ersten gefährlichen Links oder scam_pattern für ein falsches Geschenk ohne bekannten Link.

POST /image API-Pass

Erkennt explizite Bilder mit dem Bildmodell von Protector (bei einem animierten GIF werden mehrere Frames geprüft, lange Bilder werden Stück für Stück geprüft). Die Analyse läuft im Hintergrund: Du bekommst eine ID und liest dann das Ergebnis.

Sende die rohen Bytes des Bildes als Body, mit dem passenden Content-Type: image/png, image/jpeg, image/gif oder image/webp. Höchstens 8 MB.

curl https://protector-bot.com/api/v1/image \
  -H "Authorization: Bearer pk_dein_schluessel" \
  -H "Content-Type: image/png" \
  --data-binary @bild.png

{ "id": "6f1c0e2a9b4d4c7e8a3f2b1c0d9e8f7a", "status": "queued",
  "poll": "https://protector-bot.com/api/v1/image/6f1c0e2a9b4d4c7e8a3f2b1c0d9e8f7a" }

GET /image/{id}

Liest das Ergebnis. Frage alle 1 bis 2 Sekunden erneut, solange status queued oder processing ist; meist dauert es ein paar Sekunden.

{
  "id": "6f1c0e2a9b4d4c7e8a3f2b1c0d9e8f7a",
  "status": "done",
  "created_at": 1792160000,
  "result": {
    "nsfw": false,
    "label": "neutral",
    "score": 0.9412,
    "scores": { "drawing": 0.031, "hentai": 0.0021, "neutral": 0.9412, "porn": 0.0154, "sexy": 0.0103 },
    "frames": 1
  }
}

status ist queued, processing, done oder failed (dann sagt error warum, zum Beispiel too_large_to_decode). Das Bild wird gelöscht, sobald es analysiert ist; das Ergebnis wird 24 Stunden aufbewahrt.

Codebeispiele

JavaScript (Node.js 18+)

const res = await fetch('https://protector-bot.com/api/v1/text', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.PROTECTOR_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ text: message.content }),
});
const data = await res.json();
if (data.scam?.flagged || data.nsfw?.flagged) await message.delete();

Python

import os, requests

r = requests.get(
    f"https://protector-bot.com/api/v1/blacklist/{member.id}",
    headers={"Authorization": f"Bearer {os.environ['PROTECTOR_API_KEY']}"},
    timeout=5,
)
if r.ok and r.json()["blacklisted"]:
    print("Konto auf der Blacklist von Protector")

Faire Nutzung und Datenschutz

• Gesendete Texte und Links werden im Durchlauf analysiert und nicht gespeichert. Bilder werden direkt nach der Analyse gelöscht; das Ergebnis wird 24 Stunden aufbewahrt.
• Protector speichert für dein Konto: einen Fingerabdruck jedes Schlüssels, seinen Namen, sein Erstellungs- und letztes Nutzungsdatum und die Zahl der Anfragen pro Monat.
• Die Antwort der Blacklist darf nicht die alleinige Grundlage einer Sanktion sein und weder veröffentlicht noch weiterverkauft werden. Wer die API nutzt, um jemanden zu belästigen, verliert den Zugang.
• Details in den Nutzungsbedingungen und der Datenschutzerklärung.

Änderungen der API

v1 (16. Oktober 2026): erste Version. Blacklist, Links, Texte, Bilder.