L'API TunnelVision

1Authentification

Chaque serveur reçoit un jeton d'API unique (affiché une seule fois à la création). Toutes les routes l'exigent, sauf GET /health (utilisé par le healthcheck Docker) et la lecture d'un lien de rapport partagé (GET /hosted/<token>, protégée par le token de partage lui-même, pas par le jeton d'API).

curl -H "Authorization: Bearer VOTRE_JETON" \
  https://votre-id.tunnelvision.fr/health

Un jeton compromis n'ouvre que les données de votre serveur — chaque serveur vit dans son propre espace isolé (voir la page confidentialité). Vous pouvez le régénérer à tout moment ; l'ancien cesse de fonctionner immédiatement.

2Vue d'ensemble des endpoints

3Demander un rapport

GET /report accepte une fenêtre (start/end, ISO UTC), un minerai suivi (ore, ex. diamond), et quelques réglages de filtrage (gap_seconds, min_blocks, min_ore_blocks, ore_families) — les valeurs par défaut conviennent dans la grande majorité des cas.

curl -H "Authorization: Bearer VOTRE_JETON" \
  "https://votre-id.tunnelvision.fr/report?ore=diamond&start=2026-07-01&end=2026-07-08"

Réponse (abrégée) :

{
  "target": "diamond",
  "sessions": [
    {
      "pseudo": "Steve",
      "world": "world",
      "session_id": "...",
      "score": 82,
      "verdict": "fortement suspect"
    }
  ]
}

Une fenêtre modeste répond directement. Une fenêtre plus large (beaucoup de blocs à traiter) répond 202Parti en job asynchroneLa fenêtre est trop coûteuse pour répondre tout de suite — un identifiant de job est renvoyé, à interroger jusqu'à ce qu'il soit terminé.{"job_id": "a1b2c3d4e5f6", "status": "queued", "poll": "/report/jobs/a1b2c3d4e5f6"} avec un identifiant de job à interroger sur GET /report/jobs/{id} jusqu'à status=done — voir la section suivante. Ajoutez ?format=text pour une sortie en lignes clé=valeur plutôt qu'en JSON (c'est ce que lit le plugin, qui n'embarque pas de parseur JSON).

4Rendus et jobs asynchrones

POST /render fonctionne sur le même principe pour la scène 3D interactive, toujours en job (un rendu prend, au minimum, plusieurs secondes) :

curl -X POST -H "Authorization: Bearer VOTRE_JETON" \
  "https://votre-id.tunnelvision.fr/render?start=2026-07-01&end=2026-07-08&host=true"
→ {"job_id": "a1b2c3d4e5f6", "status": "queued", "poll": "/render/a1b2c3d4e5f6"}

curl -H "Authorization: Bearer VOTRE_JETON" \
  https://votre-id.tunnelvision.fr/render/a1b2c3d4e5f6

Un job interrompu par un redémarrage (mise à jour, incident) passe en error explicite plutôt que de disparaître — son état survit sur disque. Avec host=true et si votre serveur est éligible à l'hébergement en ligne, la réponse contient aussi hosted_url : un lien non-devinable, à durée limitée, consultable sans jeton d'API par quiconque le reçoit (utile pour partager un cas avec d'autres modérateurs). Gérez ces liens via /hosted-reports (liste, révocation, régénération).

5Limites et contrôle d'admission

Avant de lancer le moindre calcul, l'API estime le coût mémoire de la fenêtre demandée (nombre de blocs concernés) et refuse par avance (422Fenêtre refusée avant tout calculLa RAM prédite pour cette fenêtre dépasse le budget du serveur.{"detail": "Fenetre trop couteuse : ~2.4M blocs, ~2.1 Go predits (budget 1.6 Go)."}) si elle dépasse le budget du serveur — plutôt que de risquer un plantage à mi-calcul. La réponse d'erreur inclut toujours une fenêtre suggérée qui, elle, passerait :

{
  "detail": "Fenetre trop couteuse : ~2 400 000 blocs, ~2.1 Go de RAM predits (budget 1.6 Go). Reessayez avec une fenetre d'environ 12 jour(s)."
}

Autres bornes à connaître : 31 jours maximum par rendu (/render), un seul rapport lourd et un seul rendu à la fois par serveur (une deuxième demande simultanée reçoit 409Déjà en coursUn rapport ou un rendu du même type tourne déjà sur ce serveur — réessayez une fois terminé.{"detail": "Un rapport est deja en cours pour ce serveur."}), et une fenêtre ne peut pas remonter avant la période de rétention de votre serveur (90 jours glissants par défaut — 422Hors période de rétentionLa fenêtre demandée remonte avant le début des données disponibles sur ce serveur.{"detail": "Fenetre hors retention : donnees disponibles depuis 2026-05-20."} avec la date de coupure si vous la dépassez).

6Codes d'erreur courants

Obtenir un jeton

Pendant la bêta, l'accès se demande via un court formulaire, traité à la main. Demander un accès — ou directement par Discord / e-mail.