API REST

API REST — Référence

Intégrez les audits RGAA dans vos applications via l'API REST

Authentification

Toutes les requêtes API doivent inclure le header X-API-Key avec votre clé API.

X-API-Key: votre-cle-api

Vous pouvez générer une clé API depuis votre tableau de bord > Paramètres > API. Les clés sont préfixées par rga_ et peuvent être révoquées à tout moment depuis la même page. Chaque plan dispose d'un quota de requêtes mensuel.

Quotas par plan :

Découverte — 10 requêtes / mois
Freelance — 100 requêtes / mois
Agence — 500 requêtes / mois
Organisation — Illimité

POST
/api/ci/scan

Lance un audit RGAA sur l'URL spécifiée et retourne les résultats.

Paramètres (JSON body) :

Paramètre	Type	Requis	Description
`url`	string	Oui	URL du site à auditer
`threshold`	number	Non	Score minimum attendu (0-100, défaut : 0)
`pages`	number	Non	Nombre de pages à auditer (défaut : 5)
`waitForResults`	boolean	Non	Attendre la fin de l'audit (défaut : true)
`details`	boolean	Non	Inclure les violations détaillées, pages et patterns (défaut : false)
`diagnostics`	boolean	Non	Inclure les diagnostics de santé : liens cassés (404), pages en erreur (Cloudflare, timeout...), zones partagées détaillées et état des corrections (défaut : false, inclus automatiquement si details=true)
`cookies`	array	Non	Cookies d'authentification à injecter pour auditer les pages protégées. Chaque cookie : `{ name, value, domain?, path? }`
`authenticated`	boolean	Non	Marquer l'audit comme authentifié. Activé automatiquement si `cookies` est fourni (défaut : false)
`seedUrls`	array	Non	URLs spécifiques à auditer, bypasse la découverte automatique. Accepte les chemins relatifs (`/dashboard`, `/admin`). Utile pour les SPAs avec pages protégées.

Exemple curl :

curl -X POST https://rgaaudit.fr/api/ci/scan \
  -H "Content-Type: application/json" \
  -H "X-API-Key: votre-cle-api" \
  -d '{
    "url": "https://monsite.fr",
    "threshold": 70,
    "pages": 10
  }'

Réponse (200) :

{
  "success": true,
  "auditId": "clx1abc2d3ef4gh5ij6kl",
  "url": "https://monsite.fr",
  "score": 78,
  "thresholdMet": true,
  "summary": {
    "totalViolations": 12,
    "criticalCount": 2,
    "seriousCount": 5,
    "moderateCount": 3,
    "minorCount": 2,
    "pagesAudited": 10,
    "authPages": 3
  },
  "reportUrl": "https://rgaaudit.fr/audits/clx1abc2d3ef4gh5ij6kl",
  "diagnostics": {
    "brokenLinks": [
      { "url": "/page-inexistante", "status": 404, "errorReason": null, "depth": 2 }
    ],
    "errorPages": [
      { "url": "/api-blocked", "errorReason": "cloudflare", "errorDetails": "WAF blocked" }
    ],
    "sharedZones": {
      "header": { "count": 3, "criteria": ["1.1", "6.1"] },
      "nav": { "count": 1, "criteria": ["12.1"] }
    },
    "corrections": {
      "applied": 5,
      "pending": 12,
      "lastCorrectedAt": "2026-04-01T10:00:00Z"
    }
  }
}

Le champ diagnostics est inclus quand details=true ou diagnostics=true.

GET
/api/ci/badge/:siteKey

Retourne un badge SVG affichant le dernier score RGAA du site.

Paramètres (URL) :

Paramètre	Type	Description
`siteKey`	string	Domaine du site (ex : monsite.fr)
`style`	query string	Style du badge : flat (défaut), flat-square, for-the-badge

Exemple :

GET https://rgaaudit.fr/api/ci/badge/monsite.fr
GET https://rgaaudit.fr/api/ci/badge/monsite.fr?style=for-the-badge

Réponse : Content-Type: image/svg+xml — Image SVG du badge avec le score actuel et une couleur selon le niveau (vert ≥ 90, jaune ≥ 70, orange ≥ 50, rouge < 50).

Si le dernier audit inclut des pages protégées par authentification, le badge affiche un suffixe ✦ après le niveau de conformité (ex : « Conforme ✦ »).

Format de réponse

Toutes les réponses API suivent ce schéma JSON :

{
  "success": boolean,       // true si la requête a réussi
  "auditId": string,        // Identifiant unique de l'audit
  "url": string,            // URL auditée
  "score": number,          // Score RGAA (0-100)
  "thresholdMet": boolean,  // true si score >= threshold
  "summary": {
    "totalViolations": number,
    "criticalCount": number,
    "seriousCount": number,
    "moderateCount": number,
    "minorCount": number,
    "pagesAudited": number,
    "authPages": number       // Pages nécessitant une authentification
  },
  "violations": [           // Liste détaillée (si demandée)
    {
      "ruleId": string,
      "criteria": string,   // Critère RGAA (ex: "1.1")
      "impact": string,     // "critique" | "serieux" | "modere" | "mineur"
      "description": string,
      "count": number,
      "suggestion": string
    }
  ],
  "reportUrl": string,      // Lien vers le rapport complet
  "diagnostics": {          // Inclus si details=true ou diagnostics=true
    "brokenLinks": [{       // Pages retournant 404
      "url": string,
      "status": 404,
      "errorReason": string | null,
      "depth": number | null
    }],
    "errorPages": [{        // Pages inaccessibles (Cloudflare, captcha, timeout...)
      "url": string,
      "errorReason": string | null,
      "errorDetails": string | null,
      "depth": number | null
    }],
    "sharedZones": {        // Violations par zone partagée
      "[zone]": {
        "count": number,
        "criteria": string[]  // Critères RGAA concernés
      }
    },
    "corrections": {        // État des corrections
      "applied": number,
      "pending": number,
      "lastCorrectedAt": string | null
    }
  }
}

Codes d'erreur

Code	Statut	Description
`401`	Unauthorized	Clé API manquante ou invalide. Vérifiez le header `X-API-Key`.
`403`	Forbidden	Quota de requêtes dépassé pour votre plan. Attendez le renouvellement mensuel ou passez au plan supérieur.
`404`	Not Found	L'URL cible est inaccessible ou n'existe pas. Vérifiez que le site est en ligne et l'URL correcte.
`422`	Unprocessable	Paramètres invalides. Vérifiez le format de l'URL et les valeurs des paramètres.
`500`	Server Error	Erreur interne du serveur. Réessayez dans quelques minutes. Si le problème persiste, contactez le support.

Format d'erreur :

{
  "success": false,
  "error": {
    "code": 401,
    "message": "Invalid API key",
    "details": "The provided X-API-Key header is not valid."
  }
}

POST
/api/user/ci-key

Génère une nouvelle clé API CI/CD pour l'utilisateur connecté. Cet endpoint nécessite une session authentifiée (cookie de session Auth.js) — il n'accepte pas l'authentification par header X-API-Key.

Vous pouvez également générer cette clé depuis l'interface web dans Paramètres > API.

Exemple curl :

curl -X POST https://rgaaudit.fr/api/user/ci-key \
  -H "Cookie: authjs.session-token=VOTRE_SESSION"

Réponse (200) :

{
  "key": "rga_k7x9m2f4a8b1c3d5e6..."
}

Important :

La clé est préfixée par rga_
La clé complète n'est affichée qu'une seule fois dans la réponse
Si une clé existe déjà, l'ancienne est automatiquement révoquée

DELETE
/api/user/ci-key

Révoque la clé API CI/CD de l'utilisateur connecté. Comme pour la génération, cet endpoint nécessite une session authentifiée.

Exemple curl :

curl -X DELETE https://rgaaudit.fr/api/user/ci-key \
  -H "Cookie: authjs.session-token=VOTRE_SESSION"

Réponse (200) :

{
  "success": true,
  "message": "Clé API révoquée avec succès"
}

Après révocation, toutes les requêtes utilisant l'ancienne clé recevront une erreur 401 Unauthorized. Vous pouvez générer une nouvelle clé immédiatement.

API REST — Référence

Authentification

POST /api/ci/scan

GET /api/ci/badge/:siteKey

Format de réponse

Codes d'erreur

POST /api/user/ci-key

DELETE /api/user/ci-key

POST
/api/ci/scan

GET
/api/ci/badge/:siteKey

POST
/api/user/ci-key

DELETE
/api/user/ci-key