Documentation de l'API

1. Authentification

Une clé se fabrique depuis votre compte. Elle ne s'affiche qu'une fois : nous n'en conservons que l'empreinte, donc une clé perdue ne se retrouve pas, elle se remplace.

curl -s "https://edge-lab.io/api/v1/matches" \
  -H "Authorization: Bearer $EDGELAB_API_KEY"

Sans clé valide : 401. Une clé révoquée cesse de fonctionner au premier appel suivant, sans délai ni cache : c'est ce qui rend la coupure crédible, et c'est aussi pourquoi la clé est vérifiée en base à chaque requête.

2. L'enveloppe des réponses

Un succès porte toujours { "data": …, "meta": … }, une erreur toujours { "error": { "code": …, "message": … } }. Les codes d'erreur sont stables : unauthorized, bad_request, not_found, rate_limited, incomplete_response.

Testez error.code, jamais le message : le message est écrit pour un humain et peut être reformulé ; le code, lui, fait partie du contrat.

3. Quotas et en-têtes de limite

Deux plans, et ils ne se comptent pas de la même façon.

• Essai : 20 appels au total, à vie. Il n'y a pas de fenêtre qui se rouvre, donc pas de Retry-After : le message dit de souscrire, pas d'attendre. Remplacer sa clé ne rend pas les appels consommés.
• Abonnement : 2000 appels par jour de Paris. La fenêtre se rouvre à minuit, heure de Paris, et X-RateLimit-Reset le dit.

Toutes les réponses, succès compris, portent X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Window (day ou lifetime). Le dépassement rend 429, jamais une réponse tronquée.

4. Le paramètre viewer, et ce que votre plan en fait

Trois routes acceptent ?viewer=free|premium. La clé dit qui appelle ; viewer dit pour qui vous demandez la donnée : vous êtes autorité sur le palier de VOS lecteurs. Absent, il vaut premium.

⚠️ Le plan de la clé plafonne ce paramètre. Une clé d'essai est servie en viewer=free quoi qu'elle demande : les probabilités du modèle et leurs poids, le signal de value, la matrice de score et les statistiques de service sont absents du corps, qui porte alors locked: true. C'est ce que l'essai montre : la forme des réponses, pas la donnée qu'on vend. GET /api/v1/capabilities répond du point de vue de VOTRE clé et le dit explicitement.

Une valeur inconnue rend 400 : nous ne devinons pas à votre place.

5. Les points d'entrée

Cette liste est produite par le catalogue de l'API. Elle ne peut donc pas annoncer une route qui n'existe pas, ni en oublier une qui existe.

GET /api/v1/capabilities sert la même chose en JSON, avec les champs de chaque réponse et leur palier : un client peut donc s'adapter sans relire cette page.

6. Deux règles de lecture qui évitent les surprises

Les identifiants de joueurs sont opaques. Un player_key n'a de sens que dans cette API : comparez-les entre eux, ne les interprétez pas, ne les joignez à aucune source externe. Un même joueur a un identifiant par circuit, et une clé peut valoir null sur un match ancien dont l'identité n'est pas certaine : traitez ce cas comme « identité inconnue », jamais comme « match invalide ».

Rien n'est recalculé après coup. Un signal de value est figé au moment de la prédiction, et l'analyse d'un match commencé montre la photo d'avant-match. C'est ce qui rend le suivi vérifiable, et c'est aussi pourquoi une valeur ne changera jamais rétroactivement dans vos réponses.

7. Versionnement

Le préfixe /api/v1 est stable. Nous pouvons ajouter des champs ou des routes sans prévenir : votre client doit ignorer ce qu'il ne connaît pas. Retirer ou renommer un champ existant demanderait une nouvelle version.

8. Ce que le contrat autorise

L'usage de l'API est régi par les conditions de l'API, qui sont un contrat distinct de celui du site. En deux mots : intégrer nos analyses dans votre produit, oui ; revendre le flux en l'état ou reconstituer la base, non.

Une question, un besoin de volume, un cas d'usage particulier : hello@edge-lab.io.