API Protector

Présentation

L'API Protector est une API REST qui répond en JSON. Tous les points d'accès partent de la même adresse :

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

L'API est servie uniquement par protector-bot.com. Elle ne donne jamais accès aux machines qui font tourner le bot.

Obtenir une clé

1. Connecte-toi avec Discord sur la page développeurs.
2. Clique sur Créer une clé et donne-lui un nom (par exemple le nom de ton bot).
3. Copie la clé tout de suite : elle commence par pk_ et n'est affichée qu'une fois. Protector n'en garde qu'une empreinte.

Clé perdue, ou tu penses qu'elle a fuité ? Révoque-la sur la même page et crée-en une autre. Tu peux avoir jusqu'à 5 clés actives.

Le Pass API relève toutes les limites et débloque l'analyse d'images. Il s'achète dans la boutique de Protector sur Discord, pour 30 jours, et est lié à ton compte Discord : tes clés passent automatiquement aux limites du Pass API. Chaque nouvel achat ajoute 30 jours ; un rappel arrive en message privé 3 jours avant la fin. Sans pass, tes clés continuent de marcher avec l'offre gratuite.

Authentification

Envoie ta clé dans l'en-tête Authorization de chaque requête :

Authorization: Bearer pk_ta_cle

Garde la clé secrète : ne la mets jamais dans un dépôt public ni dans du code exécuté dans le navigateur d'un visiteur.

Offres et limites

Les compteurs mensuels repartent à zéro le 1er de chaque mois (UTC). Lire le statut d'une image (GET /image/{id}) et GET /me ne comptent pas dans le quota mensuel, seulement dans la limite par minute.

Chaque réponse porte ces en-têtes :

Erreurs

Une erreur renvoie un JSON avec un code error stable et un message lisible (en anglais) :

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

Points d'accès

GET /me

Ton offre, ses limites et ta consommation du mois.

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

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

GET /blacklist/{user_id}

Indique si un compte Discord est sur la liste noire de Protector (comptes ayant participé à des raids, des nukes ou des arnaques, confirmés par l'équipe Protector). La réponse est seulement true ou false : ni motif, ni preuve.

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

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

Une personne listée peut contester la décision sur la page de contestation. N'utilise pas cette réponse comme seule raison de sanctionner quelqu'un.

POST /link

Vérifie un lien : domaines d'arnaque connus, domaines imitateurs (lettres cyrilliques, punycode qui se lisent « discord » ou « steam ») et raccourcisseurs menant à une arnaque (la première redirection est suivie).

curl https://protector-bot.com/api/v1/link \
  -H "Authorization: Bearer pk_ta_cle" \
  -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 vaut known_scam_domain, lookalike_domain, shortener_to_scam ou null. free_host: true est ajouté quand la page est sur un hébergement gratuit, où les pages piégées sont fréquentes : pas dangereux en soi, mais à regarder de plus près.

POST /text

Analyse un message comme Protector le fait sur Discord : mots explicites (même écrits avec des points, des espaces ou des chiffres, comme p.0.r.n), faux cadeaux Nitro et chaque lien qu'il contient. Le texte n'est pas conservé.

curl https://protector-bot.com/api/v1/text \
  -H "Authorization: Bearer pk_ta_cle" \
  -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 }
  ]
}

Jusqu'à 20 liens sont analysés par message. scam.reason reprend le motif du premier lien dangereux, ou scam_pattern pour un faux cadeau sans lien connu.

POST /image Pass API

Détecte les images explicites avec le modèle d'image de Protector (plusieurs images sont vérifiées pour un GIF animé, et les images très allongées morceau par morceau). L'analyse se fait en arrière-plan : tu reçois un identifiant, puis tu lis le résultat.

Envoie les octets bruts de l'image en corps, avec le Content-Type correspondant : image/png, image/jpeg, image/gif ou image/webp. 8 Mo au plus.

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

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

GET /image/{id}

Lit le résultat. Redemande toutes les 1 à 2 secondes tant que status vaut queued ou processing ; cela prend en général quelques secondes.

{
  "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 vaut queued, processing, done ou failed (alors error dit pourquoi, par exemple too_large_to_decode). L'image est supprimée dès qu'elle a été analysée ; le résultat est gardé 24 heures.

Exemples de code

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("Compte sur la liste noire de Protector")

Usage loyal et confidentialité

• Les textes et liens envoyés sont analysés à la volée et ne sont pas conservés. Les images sont supprimées juste après l'analyse ; le résultat est gardé 24 heures.
• Protector garde, pour ton compte : l'empreinte de chaque clé, son nom, ses dates de création et de dernière utilisation, et le nombre de requêtes par mois.
• La réponse de la liste noire ne doit pas être la seule base d'une sanction, ni être publiée ou revendue. Utiliser l'API pour harceler quelqu'un met fin à l'accès.
• Détails dans les conditions d'utilisation et la politique de confidentialité.

Historique de l'API

v1 (16 octobre 2026) : première version. Liste noire, liens, textes, images.