Piloter vos tests par API.

Piloter Probant depuis un serveur ou un assistant

L’API de gestion fait depuis un serveur ce que l’interface fait à l’écran : lister, créer et modifier des brouillons, lancer, mettre en pause, reprendre, arrêter avec une décision, déployer une variante, gérer les métriques et lire les résultats. Mêmes règles, mêmes messages : une modification refusée par l’éditeur l’est aussi par l’API, et le plan d’un test se recalcule au lancement comme sur l’écran « Plan et durée ».

Les mêmes opérations existent comme outils d’un serveur MCP, pour qu’un assistant pilote vos tests.

Authentification et rôles

Créez une clé de gestion dans Réglages, onglet « Intégrations » (propriétaire de l’espace). Elle s’envoie dans l’en-tête Authorization: Bearer sk_…, depuis un serveur ou un assistant, jamais depuis une page web : une requête qui porte une origine est refusée.

• Lecture : lister les tests et les métriques, lire un test et ses résultats.
• Lecture et écriture : aussi créer, modifier, lancer, mettre en pause, arrêter, déployer.

Une clé ne fait jamais plus que la personne qui l’a créée : si son rôle baisse, celui de la clé aussi, et la clé cesse de servir si elle quitte l’espace. Les clés secrètes du back-office ne servent qu’à l’API des commandes.

Limite : 120 requêtes par minute et par clé, 240 par adresse IP ; au-delà, réponse 429 avec Retry-After.

Description OpenAPI 3.1 : GET /api/v1/openapi.json, à donner à un générateur de client ou à un outil de test d’API.

Référence

GET /api/v1/experiments Lister les tests

Tests de l’espace, du plus récent au plus ancien, avec leur statut et leurs visiteurs exposés. Clé : toute clé de gestion (la lecture suffit).

• ?status= : Ne garder que les tests de ce statut.

POST /api/v1/experiments Créer un brouillon

Mêmes règles que l’éditeur : deux à cinq variantes, l’originale « a » sans modification, modifications assainies (une modification refusée fait refuser tout le brouillon). Clé : « lecture et écriture », ou un rôle personnalisé qui donne la permission « Préparer des tests » ; jamais plus que les permissions de la personne qui a créé la clé.

GET /api/v1/experiments/{key} Lire un test

Hypothèse, ciblage, variantes et leurs modifications, métrique de décision, plan figé au lancement, dernière décision. Clé : toute clé de gestion (la lecture suffit).

PATCH /api/v1/experiments/{key} Modifier un brouillon

Les champs absents gardent leur valeur. Un test lancé ne se modifie plus (409). Clé : « lecture et écriture », ou un rôle personnalisé qui donne la permission « Préparer des tests » ; jamais plus que les permissions de la personne qui a créé la clé.

POST /api/v1/experiments/{key}/launch Lancer un brouillon

Le plan (visiteurs par variante, durée, points de contrôle) est recalculé par le moteur à partir du trafic déclaré, comme sur l’écran « Plan et durée ». Refusé au quota du forfait (402) ou sans place dans la zone (409). Un brouillon de test d’optimisation se lance par POST /experiments/{key}/bandit/launch (409 ici). guardrails : clés des métriques garde-fous, figées avec le plan, aux règles de l’écran ; un test par alternance ou par zones refuse la vitesse, la rétention et, par zones, les montants (422). Un tel test se lance ici aussi : looks choisit ses points de contrôle (une lecture, à la fin, par défaut) ; dailyVisitors reste exigé mais n’y est pas lu (rien ne se calcule en visiteurs). Clé : « lecture et écriture », ou un rôle personnalisé qui donne la permission « Lancer et arrêter les tests » ; jamais plus que les permissions de la personne qui a créé la clé.

POST /api/v1/experiments/{key}/pause Mettre en pause

Les visiteurs voient l’originale ; le test reprend sur la même tranche et avec les mêmes affectations. Clé : « lecture et écriture », ou un rôle personnalisé qui donne la permission « Lancer et arrêter les tests » ; jamais plus que les permissions de la personne qui a créé la clé.

POST /api/v1/experiments/{key}/resume Reprendre

Reprend un test en pause. Clé : « lecture et écriture », ou un rôle personnalisé qui donne la permission « Lancer et arrêter les tests » ; jamais plus que les permissions de la personne qui a créé la clé.

POST /api/v1/experiments/{key}/stop Arrêter avec une décision

La décision et l’arrêt sont écrits ensemble. Un test arrêté ne repart pas. Clé : « lecture et écriture », ou un rôle personnalisé qui donne la permission « Lancer et arrêter les tests » ; jamais plus que les permissions de la personne qui a créé la clé.

POST /api/v1/experiments/{key}/rollout Déployer une variante

Déploiement progressif par paliers, garde-fous de l’espace surveillés en continu, retour arrière automatique. Consigne la décision de déployer. Clé : « lecture et écriture », ou un rôle personnalisé qui donne la permission « Déployer la variante gagnante » ; jamais plus que les permissions de la personne qui a créé la clé.

GET /api/v1/experiments/{key}/results Lire les résultats

Par métrique (principale, puis secondaires et garde-fous de l’espace) et par variante : visiteurs, convertis, sommes, puis écart relatif, fourchette, p-value et verdict calculés par le moteur. decisionAuthorized dit si le plan autorise à conclure (échantillon atteint ou borne franchie). Quand l’espace a activé la lecture bayésienne, bayesian l’ajoute pour la métrique principale (schéma BayesianReading) : probabilité que la variante fasse mieux, intervalle de crédibilité et perte attendue, avec un a priori centré sur zéro tiré des tests arrêtés de l’espace ; elle ne décide rien. Une métrique à fenêtre (rétention, ou conversion du CRM : window.kind « deferred ») ne compte que les visiteurs dont la fenêtre est refermée ; window.pendingVisitors dit combien attendent. Clé : toute clé de gestion (la lecture suffit).

• ?format= : « csv » : le même rapport en CSV (séparateur « ; », virgule décimale).

POST /api/v1/bandits Créer un test d’optimisation

Brouillon de test d’optimisation (bandit), mêmes champs qu’un brouillon plus bandit (part minimale, apprentissage, parts par appareil). Il maximise les conversions, ou un montant par visiteur, pendant le test ; il ne prouve pas qu’une variante est meilleure. Se lance par POST /experiments/{key}/bandit/launch, avec les mêmes règles qu’un test A/B. Clé : « lecture et écriture », ou un rôle personnalisé qui donne la permission « Préparer des tests » ; jamais plus que les permissions de la personne qui a créé la clé.

POST /api/v1/experiments/{key}/bandit Faire d’un brouillon un test d’optimisation

Type et réglages d’un brouillon ; un test lancé garde son type (409). Clé : « lecture et écriture », ou un rôle personnalisé qui donne la permission « Préparer des tests » ; jamais plus que les permissions de la personne qui a créé la clé.

POST /api/v1/experiments/{key}/bandit/launch Lancer un test d’optimisation

Lance un brouillon d’optimisation : métrique à maximiser (un taux, ou un montant par visiteur comme le chiffre d’affaires, plafonné au centile réglé sur la métrique), part de la zone, tests simultanés, et au besoin ses réglages (sinon ceux du brouillon). Mêmes règles qu’un test A/B lancé par l’API : refusé quand l’espace exige qu’un autre membre approuve chaque lancement (409, la demande se fait dans Probant), au quota du forfait (402), sans place dans la zone ou pour un test A/B (409). La première époque, à parts égales, est scellée avec le plan. Il maximise les conversions pendant le test ; il ne prouve pas qu’une variante est meilleure. Clé : « lecture et écriture », ou un rôle personnalisé qui donne la permission « Lancer et arrêter les tests » ; jamais plus que les permissions de la personne qui a créé la clé.

GET /api/v1/experiments/{key}/bandit Lire un test d’optimisation

Époques datées et leurs parts, part actuelle, écart de chaque variante estimé époque par époque puis combiné, fourchette toujours valide, conversions gagnées par rapport à des parts égales, répartition contrôlée par époque. Pour un bandit contextuel, la même lecture par appareil (reading.byDevice), et l’ensemble par strates époque × appareil. Jamais de gagnant. Les résultats A/B (/results) d’un test d’optimisation répondent 409 : leur comparaison naïve serait biaisée. Clé : toute clé de gestion (la lecture suffit).

POST /api/v1/experiments/{key}/unit Choisir ce qu’un brouillon tire au sort

Visiteurs (test A/B), créneaux (alternance : un prix, un stock) ou zones géographiques (régions ou pays : des frais de livraison). Deux versions exactement pour les créneaux et les zones ; un test lancé garde son unité (409). Lancement dans Probant, avec les mêmes règles qu’un test A/B. Clé : « lecture et écriture », ou un rôle personnalisé qui donne la permission « Préparer des tests » ; jamais plus que les permissions de la personne qui a créé la clé.

GET /api/v1/experiments/{key}/unit Lire un test par alternance ou par zones géographiques

Calendrier des créneaux ou zones tirées au sort, figés au lancement ; état (draft, waiting, collecting, read) ; une fois assez de paires, écart par paires pesées par leur trafic, fourchettes (Student, Fieller pour l’effet relatif), test de permutation et signature. Aucun chiffre d’effet tant que l’état n’est pas read. Les résultats A/B (/results) d’un tel test répondent 409 : lu par visiteur, il donnerait des fourchettes trop étroites. guardrails : garde-fous lus au dernier point de contrôle atteint, sur les mêmes paires (fourchette relative au niveau du point, breached quand toute la fourchette dépasse la limite : le test s’arrête seul) ; decision : dernière décision consignée, automatic pour un arrêt par garde-fou, avec sa raison dans note. target : effet relatif visé, le plus petit écart détectable du plan, figé au lancement (null sans historique) ; reading.futility : à un point avant le dernier, la chance de conclure d’ici la fin si le vrai écart valait cet effet, et futile sous le seuil. Une recommandation : rien ne s’arrête seul pour futilité. Clé : toute clé de gestion (la lecture suffit).

GET /api/v1/metrics Lister les métriques

Catalogue de l’espace : type, événement ou objectif, rôle, règle de garde-fou. Clé : toute clé de gestion (la lecture suffit).

POST /api/v1/metrics Créer une métrique

Événement envoyé par probant.track(…), ou objectif sans code (clic, envoi de formulaire, visite de page). Clé : « lecture et écriture », ou un rôle personnalisé qui donne la permission « Créer des métriques » ; jamais plus que les permissions de la personne qui a créé la clé.

GET /api/v1/metrics/{key} Lire une métrique

Une métrique du catalogue. Clé : toute clé de gestion (la lecture suffit).

PATCH /api/v1/metrics/{key} Modifier une métrique

Ce qu’une métrique mesure (type, événement, objectif) ne change plus une fois qu’un test lancé décide sur elle (409). Clé : « lecture et écriture », ou un rôle personnalisé qui donne la permission « Modifier et supprimer les métriques » ; jamais plus que les permissions de la personne qui a créé la clé.

DELETE /api/v1/metrics/{key} Supprimer une métrique

Refusé tant qu’un test en fait sa métrique principale (409). Clé : « lecture et écriture », ou un rôle personnalisé qui donne la permission « Modifier et supprimer les métriques » ; jamais plus que les permissions de la personne qui a créé la clé.

POST /api/v1/multivariate-experiments Créer un test multivarié

Brouillon d’un test multivarié : de 2 à 4 sections, chacune de 2 à 4 niveaux (le premier est l’originale), 16 combinaisons au plus. Probant génère le plan factoriel complet ; chaque combinaison est une variante ordinaire dont les modifications réunissent celles de ses niveaux. Mêmes contrôles et même assainissement que l’éditeur. Se lance par POST /experiments/{key}/launch : le plan factoriel y est calculé au trafic mesuré de l’espace (déclaré à défaut), un seul regard à la fin, interactions pour annoncer les interactions d’ordre 2. Clé : « lecture et écriture », ou un rôle personnalisé qui donne la permission « Préparer des tests » ; jamais plus que les permissions de la personne qui a créé la clé.

GET /api/v1/experiments/{key}/sections Lire un test multivarié par section

Effets principaux de chaque section (moyenne marginale de chaque niveau, écart à l’originale, fourchette), interactions d’ordre 2 (différence des différences), p-values ajustées par Holm sur les comparaisons annoncées au plan, et recommandation. Sans interaction concluante, la recommandation suit les effets principaux. 409 pour un test A/B. Clé : toute clé de gestion (la lecture suffit).

GET /api/v1/experiments/{key}/integration Intégrer une variante au site

Les modifications d’une variante réécrites en code que le site garde, sans le script Probant : une feuille CSS (styles, états, éléments masqués, CSS de variante) et un script autonome et idempotent (textes, contenus assainis, blocs, attributs, images, déplacements, JavaScript de variante repris tel quel). Le script reproduit le ciblage du test (pages, appareils, audience) ; quand le test ne visait qu’une partie des visiteurs, il porte aussi la feuille et la pose pour eux seuls (css vaut alors null), et warnings nomme les critères d’audience qu’il ne peut pas vérifier (pays, attributs). Avec les fichiers à déposer dans assets/ et l’extrait de layout/theme.liquid pour Shopify, les consignes, et ce qui serait mieux réécrit dans le thème (sélecteurs fragiles compris). Sans variant, celle de la dernière décision « déployer ». Une fois le code en ligne, arrêtez le test ou ramenez son déploiement à l’originale. Clé : « lecture et écriture », ou un rôle personnalisé qui donne la permission « Déployer la variante gagnante » ; jamais plus que les permissions de la personne qui a créé la clé.

• ?variant= : Clé de la variante à intégrer (« b ») ; par défaut, celle de la décision « déployer ».
• ?format= : json (par défaut), ou un seul fichier à enregistrer tel quel.

GET /api/v1/widgets Lister les gabarits de widgets

Bandeau, compte à rebours, pop-in, badge, réassurance, barre d’action, date de livraison, preuve sociale, code promo, livraison offerte : nom, description, comportement chargé à la demande (compte à rebours, pop-in, date de livraison, preuve sociale, code promo, livraison offerte ; barre d’action qui clique un bouton de la page), paramètres (schéma JSON) et un exemple complet. Clé : toute clé de gestion (la lecture suffit).

POST /api/v1/widgets Produire les modifications d’un widget

Les modifications ordinaires d’un widget (un insert au HTML assaini, puis des style posés par le CSSOM), avec ses avertissements (contraste, échéance passée) et sa description lisible. Rien n’est enregistré : à ajouter aux changes d’une variante. Clé : toute clé de gestion (la lecture suffit).

POST /api/v1/experiments/{key}/widgets Ajouter un widget à un brouillon

Produit le widget et l’ajoute à la fin des modifications de la variante, avec les règles d’un brouillon (assainissement, 50 modifications au plus par variante, journal). Un test lancé ne se modifie plus (409). Clé : « lecture et écriture », ou un rôle personnalisé qui donne la permission « Préparer des tests » ; jamais plus que les permissions de la personne qui a créé la clé.

Exemples

Créer un brouillon

curl -X POST https://app.probant.app/api/v1/experiments \
  -H "Authorization: Bearer sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Date de livraison estimée",
    "zone": "Fiche produit",
    "urlPattern": "/produits/*",
    "variants": [
      { "key": "a", "name": "Originale", "changes": [] },
      { "key": "b", "name": "Date estimée", "changes": [
        { "kind": "insert", "selector": "[data-add-to-cart]", "position": "afterend",
          "html": "<p>Livré sous 2 jours ouvrés</p>" }
      ] }
    ]
  }'

La première variante est l’originale, a, sans modification. Les modifications (insert, text, style, attribute, hide) passent par le même assainissement que celles de l’éditeur.

Lancer

curl -X POST https://app.probant.app/api/v1/experiments/date-de-livraison-estimee/launch \
  -H "Authorization: Bearer sk_…" \
  -H "Content-Type: application/json" \
  -d '{ "metric": "commande", "baselineRate": 0.032, "dailyVisitors": 4000, "mde": 0.05 }'

Le taux de référence et le trafic déclarés servent au calcul du plan (visiteurs par variante, durée, points de contrôle) ; Probant ne croit jamais un plan envoyé tout fait.

Lire les résultats

curl https://app.probant.app/api/v1/experiments/date-de-livraison-estimee/results \
  -H "Authorization: Bearer sk_…"

# Le même rapport en CSV (séparateur « ; », virgule décimale)
curl "https://app.probant.app/api/v1/experiments/date-de-livraison-estimee/results?format=csv" \
  -H "Authorization: Bearer sk_…" -o rapport.csv

decisionAuthorized vaut sample quand l’échantillon prévu est atteint, look quand une borne d’un point de contrôle est franchie, null sinon : avant, une fourchette qui exclut 0 n’autorise pas à conclure.

Réponses et erreurs

Serveur MCP

Adresse : /api/v1/mcp, transport HTTP (« Streamable HTTP »), sans état. Deux façons de s’y brancher.

Sans clé, par OAuth : dans Claude, ChatGPT ou tout assistant qui se connecte ainsi, ajoutez seulement l’adresse. L’assistant ouvre Probant, où vous vous connectez, choisissez l’espace et l’accès (lecture, ou lecture et écriture), jamais plus que votre propre rôle. L’assistant apparaît alors dans Réglages → Intégrations, d’où vous le déconnectez. Avec Claude Code :

claude mcp add --transport http probant https://app.probant.app/api/v1/mcp

Avec une clé de gestion, pour un script ou un assistant qui n’en connaît pas d’autre :

claude mcp add --transport http probant https://app.probant.app/api/v1/mcp \
  --header "Authorization: Bearer sk_…"

Pour un client qui se configure par fichier :

{
  "mcpServers": {
    "probant": {
      "type": "http",
      "url": "https://app.probant.app/api/v1/mcp",
      "headers": { "Authorization": "Bearer sk_…" }
    }
  }
}

Lancer, arrêter et déployer ne se défont pas. Appelés sans confirm: true, ces outils ne font rien et renvoient un aperçu (plan et durée, décision, paliers et garde-fous) que l’assistant montre à la personne ; il ne les rappelle avec confirm: true qu’après son accord explicite.

Alertes : Slack et webhooks signés

Dans Réglages, onglet « Intégrations », le propriétaire ajoute un webhook entrant Slack ou une adresse https qui recevra les alertes, et choisit lesquelles. Chaque fait n’est envoyé qu’une fois, même constaté par plusieurs lectures.

• experiment.decision : Le plan autorise à conclure : échantillon atteint ou borne d’un point de contrôle franchie.
• experiment.srm : Les visiteurs ne se répartissent pas comme prévu entre les variantes (SRM) : les résultats sont bloqués.
• rollout.rolled_back : Un déploiement est revenu seul à l’originale parce qu’un garde-fou a dépassé sa limite.
• quota.reached : Les visiteurs testés du mois atteignent le forfait : aucun nouveau test ne démarre.
• experiment.interaction : Deux tests qui se chevauchent interagissent : l’effet de l’un change selon la variante de l’autre.
• experiment.fading : L’écart d’un test en cours faiblit nettement des premiers jours à la suite : un effet de nouveauté gonfle le verdict.
• flag.killed : Un drapeau a été coupé en urgence : sa valeur « coupé » est servie partout au prochain rafraîchissement des SDK.
• bandit.floor : Dans un test d’optimisation, une variante ne reçoit plus que sa part minimale depuis sept jours : envisagez de l’arrêter ou de basculer vers un déploiement.
• experiment.display : Une modification d’un test en cours ne s’applique pas chez une part démontrée des visiteurs exposés, dès le premier jour (sélecteur faux, autre page), ou cesse de s’appliquer (thème mis à jour, page changée) : la variante mesurée n’est plus celle que vous avez conçue.

Un webhook reçoit un POST JSON, signé avec le secret montré une seule fois à l’ajout de la destination :

POST https://exemple.fr/webhooks/probant
Content-Type: application/json
Probant-Event: experiment.decision
Probant-Delivery: 0b6f…
Probant-Signature: t=1794299400,v1=5d1c…

{
  "id": "0b6f…",
  "type": "experiment.decision",
  "occurredAt": "2026-11-10T08:30:00.000Z",
  "workspace": { "slug": "maison-lune", "name": "Maison Lune" },
  "title": "« Date de livraison estimée » : B fait mieux que l’originale.",
  "text": "Écart estimé +6,1 % sur « Commande »…",
  "url": "https://app.probant.app/experiences/date-de-livraison-estimee",
  "data": { "experiment": { "key": "…", "name": "…" }, "verdict": "winner", "effect": { "relative": 0.061, "lower": 0.012, "upper": 0.11 } }
}

La signature est un HMAC-SHA256 de « horodatage.corps brut ». Vérifiez-la, en temps constant, et refusez un horodatage de plus de 5 minutes :

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyProbant(secret: string, header: string, rawBody: string): boolean {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // trop ancien : rejoué ?
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  const given = Buffer.from(v1 ?? "", "hex");
  return given.length === expected.length && timingSafeEqual(expected, given);
}

Probant n’envoie qu’aux adresses publiques, en https, sans suivre de redirection, et n’attend pas plus de 5 secondes une réponse. Un envoi raté n’est pas retenté : l’onglet « Intégrations » montre l’erreur, et « Envoyer un essai » vérifie la destination.

Paquet de l’aide serveur

L’affectation côté serveur (assignRequest) est prête en paquet npm, @probant/edge, sans dépendance, pour Next.js, Cloudflare Workers ou tout serveur qui parle fetch. Il n’est pas encore publié sur npm ; dès qu’il le sera :

npm install @probant/edge

// proxy.ts (Next.js 16), à la racine du site
import { NextResponse, type NextRequest } from "next/server";
import { assignRequest, assignedVariants, createConfigLoader } from "@probant/edge";

const loadConfig = createConfigLoader({ key: process.env.NEXT_PUBLIC_PROBANT_KEY!, endpoint: "https://app.probant.app" });

export async function proxy(request: NextRequest) {
  const config = await loadConfig();
  if (!config) return NextResponse.next();
  const { setCookie, assignments } = assignRequest({
    cookieHeader: request.headers.get("cookie"),
    url: request.url,
    userAgent: request.headers.get("user-agent"),
    config,
    consent: request.cookies.get("consentement")?.value === "oui",
  });
  const headers = new Headers(request.headers);
  headers.set("x-probant-variants", JSON.stringify(assignedVariants(assignments)));
  const response = NextResponse.next({ request: { headers } });
  if (setCookie) response.headers.append("set-cookie", setCookie);
  return response;
}

createConfigLoader garde la configuration une minute en mémoire et sert l’ancienne si Probant ne répond pas : le site n’attend jamais Probant.

La même aide existe en PHP, Python, Ruby et Go, sans dépendance, avec le même cache de la configuration. Chaque paquet est vérifié contre la référence par des milliers de cas communs : même visiteur, même variante que le script. Ils ne sont pas encore publiés sur Packagist, PyPI ni RubyGems.