Référence de l'API

API publique heyGRC : points de terminaison pour les cadres et la configuration des revues, avec les formats des requêtes et réponses.

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`

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

200

{
  "profile": { "company": "Acme Inc", "...": "..." },
  "frameworks": ["ISO_27001", "SOC_2", "GDPR"],
  "eu_inference": false
}

`PUT /v1/config`

Remplace entièrement la configuration de votre organisation. Idempotent : le corps représente l'état souhaité complet (tout ce que vous omettez est effacé). Portée : config:write.

Une exception au remplacement complet : eu_inference est optionnel et persistant. L'omettre laisse la valeur actuelle de l'organisation inchangée ; envoyer un booléen la définit (les non-booléens sont rejetés). Ne comptez pas sur un PUT omissif pour la réinitialiser.

En-têtes : Content-Type: application/json ; Idempotency-Key: <string> optionnel (journalisé pour des tentatives sûres).

Corps

Champ	Type	Notes
`profile`	objet (requis)	Contexte d'entreprise libre. Doit être un objet JSON, ≤ 16 Ko, profondeur d'imbrication maximale de 4, les valeurs sont des chaînes / nombres / booléens / tableaux de ceux-ci.
`frameworks`	string[] (requis)	Les identifiants des cadres avec lesquels vous devez être conforme. Chaque identifiant doit figurer dans le catalogue - les identifiants inconnus sont rejetés, pas silencieusement ignorés.
`eu_inference`	booléen (optionnel)	Persistant : omis = valeur actuelle conservée ; booléen = définie. Les non-booléens sont rejetés.

200

{ "ok": true, "profile": { "...": "..." }, "frameworks": ["ISO_27001", "SOC_2", "GDPR"] }

Un 200 n'est retourné qu'après que le changement et son enregistrement d'audit ont été validés ensemble, donc une écriture réussie est toujours auditable.

Erreurs

Format JSON stable pour chaque erreur :

{ "error": { "code": "unknown_frameworks", "message": "unknown framework ids: FOO", "unknown": ["FOO"] } }

Statut	`code`	Signification
400	`invalid_request`	Corps non JSON, forme du corps incorrecte, ou une clé a été passée dans l'URL.
401	`unauthorized`	Clé manquante, mal formée, invalide, expirée ou révoquée.
403	`forbidden`	La clé ne possède pas la portée requise (`config:read` / `config:write`).
422	`invalid_profile`	`profile` n'est pas un objet, est trop volumineux ou trop profondément imbriqué.
422	`unknown_frameworks`	Un ou plusieurs identifiants de cadre ne figurent pas dans le catalogue (voir `unknown`).
429	`rate_limited`	Trop de requêtes ; ralentissez.
405	`method_not_allowed`	Méthode HTTP non prise en charge sur ce point de terminaison.
500	`internal`	Erreur serveur inattendue ; réessayez avec un backoff.

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.

Référence de l'API

GET /v1/config

PUT /v1/config