Référence de l'API

URL de base : https://api.heygrc.com

Toutes les requêtes s'authentifient avec une clé API par organisation en tant que jeton Bearer :

Authorization: Bearer hgrc_...

Une clé appartient à une organisation heyGRC (une par installation de l'application GitHub) et possède des portées (config:read, config:write). Envoyez la clé uniquement dans l'en-tête - les clés transmises dans l'URL sont rejetées (400), afin d'éviter leur fuite dans les journaux et les référents. L'organisation sur laquelle agit une requête est toujours dérivée de la clé, donc une clé ne peut lire ou écrire que la configuration de sa propre organisation.

GET /v1/config

Renvoie la configuration actuelle de votre organisation. Portée : config:read.

200

{
  "profile": { "company": "Acme Inc", "...": "..." },
  "frameworks": ["ISO_27001", "SOC_2", "GDPR"],
  "eu_inference": false,
  "review_language": "en",
  "commitments": [
    { "area": "logging", "implementation": "never log email or full IP", "source": "Logging Policy 4.2" }
  ],
  "commitments_updated_at": "2026-08-26T22:00:00Z"
}

PUT /v1/config

Envoyez uniquement ce que vous modifiez. Chaque champ est facultatif : un champ omis conserve sa valeur actuelle, un champ présent est remplacé. Cela rend les flux de travail des agents sûrs : PUT modifiez uniquement le champ que vous souhaitez changer, sans lecture-modification-écriture de l'ensemble de la configuration. Les champs de premier niveau inconnus sont rejetés avec un code 400, donc une faute de frappe ne provoque jamais de non-opération silencieuse. Portée : config:write.

En-têtes : Content-Type: application/json ; Idempotency-Key: <string> (facultatif, enregistré pour des relances sûres).

Corps

200

{ "ok": true, "commitments": [ { "area": "logging", "implementation": "never log email or full IP" } ] }

Seuls les champs que vous avez envoyés sont renvoyés. Un code 200 n'est renvoyé qu'après que le changement et son enregistrement d'audit sont validés ensemble, donc une écriture réussie est toujours traçable.

Erreurs

Format JSON stable pour chaque erreur :

{ "error": { "code": "unknown_frameworks", "message": "unknown framework ids: FOO", "unknown": ["FOO"] } }
| 400 | `invalid_request` | Champ(s) de premier niveau inconnu(s), ou un corps de requête sans aucun des champs connus (mise à jour vide). |
| 422 | `invalid_commitments` | `commitments` n'est pas un tableau de lignes valides (zone inconnue ou en double, texte trop long, caractères de contrôle). `null` est un 400 : utilisez `[]` pour effacer. |

Limites de débit

Des plafonds de requêtes par clé et par IP protègent le service. Restez en dessous d'environ 1 requête/seconde et vous ne verrez jamais de 429. La configuration est un plan de contrôle - vous la définissez occasionnellement, pas dans une boucle intensive.

GET /v1/frameworks

Le catalogue complet et lisible par machine (sans authentification - pointez votre agent ici pour découvrir les identifiants valides) :

{ "frameworks": [ { "id": "ISO_27001", "name": "ISO 27001:2022", "region": "International" }, … ] }

Catalogue des cadres

Le catalogue de cadres de heyGRC est retourné par GET /v1/frameworks (le nombre augmente au fil du temps ; ne le codez pas en dur). Passez l'identifiant canonique dans frameworks. Les identifiants les plus courants :

ISO_27001, ISO_42001, ISO_27701, ISO_22301, ISO_9001, SOC_2, GDPR, UK_GDPR, HIPAA, CCPA, EU_AI_ACT, NIST_CSF, NIST_800_53, NIST_800_171, NIST_AI_RMF, DORA, TISAX, CMMC, FEDRAMP, CYFUN, AU_ESSENTIAL_EIGHT, et NIS 2 sous NIS_2 ainsi que les variantes par pays (NIS_2_DE, NIS_2_FR, NIS_2_IT, …).

Une requête PUT avec un identifiant en dehors du catalogue est rejetée avec 422 unknown_frameworks et les identifiants problématiques sont renvoyés, afin que votre agent puisse se corriger automatiquement.