Votre première requête à l'API, en moins de 5 minutes.

Récupérez votre clé API.

Toutes les requêtes B2B s'authentifient avec le header X-Api-Key, qui porte votre clé personnelle préfixée wm_. Créez un compte (plan Découverte gratuit, sans carte bancaire) — vous retrouverez vos clés dans votre dashboard.

X-Api-Key: wm_abcdef0123456789abcdef0123456789

GET /v1/score

Le score composite national 0-100. Remplacez YOUR_API_KEY par votre vraie clé, puis choisissez votre langage — c'est le même appel dans les quatre.

$ curl -H "X-Api-Key: YOUR_API_KEY" \
    https://api.wattmind.fr/v1/score

const res = await fetch("https://api.wattmind.fr/v1/score", {
  headers: { "X-Api-Key": "YOUR_API_KEY" }
});
const score = await res.json();
console.log(`Score : ${score.globalScore}/100 — ${score.level}`);

import requests

res = requests.get(
    "https://api.wattmind.fr/v1/score",
    headers={"X-Api-Key": "YOUR_API_KEY"}
)
score = res.json()
print(f"Score : {score['globalScore']}/100 — {score['level']}")

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Api-Key", "YOUR_API_KEY");

var score = await client.GetFromJsonAsync<JsonElement>(
    "https://api.wattmind.fr/v1/score");

Console.WriteLine($"Score : {score.GetProperty(\"globalScore\")}/100");

Un score global, quatre sous-scores.

Le score global est une moyenne pondérée sur quatre dimensions — prix · carbone · réseau · adéquation. Chaque sous-score (0-100) porte un detail explicatif prêt à afficher. Comment chaque dimension est notée : Méthodologie.

{
  "computedAt":     "2026-08-09T15:33:29.0855135+00:00",
  "globalScore":    85,
  "level":          "Optimal",
  "recommendation": "Créneau favorable pour vos process flexibles : recharge VE, HVAC, batteries, data center. […]",
  "subScores": [
    { "dimension": "price",    "value": 75,  "detail": "Prix spot 50.6 €/MWh | Heures creuses" },
    { "dimension": "carbon",   "value": 92,  "detail": "Mix domestique 92% décarboné" },
    { "dimension": "grid",     "value": 100, "detail": "Ecowatt Optimal | équilibrage 100/100" },
    { "dimension": "adequacy", "value": 74,  "detail": "headroom import 100/100 | tendance indispos 35/100" }
  ],
  "confidence":     100,
  "status":         "ok",
  // quelle source a répondu — c'est ce qui explique le confidence ci-dessus
  "sourceAvailability": { "spotPrice": true, "ecowatt": true, "actualGenerations": true, … },
  "weightsApplied": { "price": 0.3, "carbon": 0.3, "grid": 0.2, "adequacy": 0.2 },
  // null = pondération nationale. "balanced" n'est PAS servi par défaut.
  "profileApplied": null,
  "spotPriceEurPerMWh": 50.64,
  "ecowattStatus": "Optimal",
  // version de chaque formule : deux points ne sont comparables qu'à version égale
  "methodologyVersions": { "score": 1, "carbon": 1, "confidence": 1, "consumption": 1 }
}

Vérifiez l'état avant d'agir.

Quand une source RTE est en timeout, l'API ne vous renvoie pas un faux zéro : elle expose un status explicite et le header X-WattMind-Confidence. Lisez-les avant de déclencher une action coûteuse (effacement industriel, pricing d'un certificat). Comment l'indice de fiabilité est calculé : Méthodologie.

corps de la réponse · 503

HTTP/1.1 503 Service Unavailable
X-WattMind-Confidence: insufficient

{
  "error":          "insufficient_data",
  "confidence":     41,
  "missingSources": ["spotPrice", "actualGenerations"]
}

exemple · garde avant action

const res = await fetch("/v1/score", { headers });

if (res.status === 503) {
  // insufficient_data : missingSources nomme la ou les sources en cause,
  // de quoi tracer l'incident sans ouvrir un ticket.
  const { missingSources } = await res.json();
  console.warn("score indisponible — sources manquantes :", missingSources);
  return scheduleRetry(10 * 60 * 1000); // prochain cycle de collecte
}

const { globalScore, confidence, status } = await res.json();
if (status === "degraded" && confidence < 60) {
  // décision à fort enjeu : on attend une lecture "ok"
  return;
}

triggerLoadShedding(globalScore);

Quotas et codes d'erreur.

Chaque réponse porte vos compteurs minute. Le débit par minute est la seule limite appliquée sur les plans payants : le volume mensuel y est un repère de dimensionnement, pas un plafond. Les compteurs mensuels ne sont donc exposés que sur le plan Découverte, où le quota est réellement appliqué.

X-RateLimit-Limit-Minute:     60
X-RateLimit-Remaining-Minute: 58
X-WattMind-Confidence:        ok

HTTP/1.1 429 Too Many Requests
Retry-After: 38

{
  "status":  429,
  "error":   "rate_limit_exceeded",
  "traceId": "0HN5..."
}

authentification refusée · 401

{
  "status":  401,
  "error":   "Unauthorized",
  "traceId": "0HN5..."
}

Une fois votre premier appel passé.

Le reste de l'API, dans l'ordre où on l'adopte en général. Ce qui dépend d'un palier le dit.

$ curl -H "X-Api-Key: YOUR_API_KEY" \
    "https://api.wattmind.fr/v1/score?profile=green-first"