Riferimento API
API pubblica heyGRC: endpoint per framework e configurazione delle revisioni, con forme di richiesta e risposta.
URL di base: https://api.heygrc.com
Tutte le richieste si autenticano con una chiave API per organizzazione come token Bearer:
Authorization: Bearer hgrc_...Una chiave appartiene a una singola organizzazione heyGRC (una per installazione della GitHub App) e possiede ambiti (config:read, config:write). Invia la chiave solo nell'intestazione - le chiavi passate nell'URL vengono rifiutate (400), per evitare che vengano trapelate nei log e nei referrer. L'organizzazione su cui agisce una richiesta è sempre derivata dalla chiave, quindi una chiave può leggere o scrivere solo la configurazione della propria organizzazione.
GET /v1/config
Restituisce la configurazione corrente della tua organizzazione. Ambito: config:read.
200
{
"profile": { "company": "Acme Inc", "...": "..." },
"frameworks": ["ISO_27001", "SOC_2", "GDPR"],
"eu_inference": false
}PUT /v1/config
Sostituzione completa della configurazione della tua organizzazione. Idempotente: il corpo rappresenta lo stato desiderato completo (tutto ciò che viene omesso viene cancellato). Ambito: config:write.
Un'eccezione alla sostituzione completa: eu_inference è opzionale e persistente. Ometterlo lascia invariato il valore attuale dell'organizzazione; inviare un booleano lo imposta (i non booleani vengono rifiutati). Non fare affidamento su una PUT che lo omette per reimpostarlo.
Intestazioni: Content-Type: application/json; opzionale Idempotency-Key: <string> (registrato per ripetizioni sicure).
Corpo
| Campo | Tipo | Note |
|---|---|---|
profile | object (obbligatorio) | Contesto aziendale libero. Deve essere un oggetto JSON, ≤ 16 KB, profondità di nidificazione massima 4, valori sono stringhe / numeri / booleani / array di questi. |
frameworks | string[] (obbligatorio) | Gli id dei framework con cui devi essere conforme. Ogni id deve essere presente nel catalogo - gli id sconosciuti vengono rifiutati, non eliminati silenziosamente. |
eu_inference | booleano (opzionale) | Persistente: omesso = valore attuale mantenuto; booleano = impostato. I non booleani vengono rifiutati. |
200
{ "ok": true, "profile": { "...": "..." }, "frameworks": ["ISO_27001", "SOC_2", "GDPR"] }Un 200 viene restituito solo dopo che la modifica e il relativo record di audit sono stati confermati insieme, quindi una scrittura riuscita è sempre verificabile.
Errori
Forma JSON stabile per ogni errore:
{ "error": { "code": "unknown_frameworks", "message": "id framework sconosciuti: FOO", "unknown": ["FOO"] } }| Stato | code | Significato |
|---|---|---|
| 400 | invalid_request | Corpo non JSON, forma del corpo errata, o una chiave è stata passata nell'URL. |
| 401 | unauthorized | Chiave mancante, malformata, non valida, scaduta o revocata. |
| 403 | forbidden | La chiave non possiede l'ambito richiesto (config:read / config:write). |
| 422 | invalid_profile | profile non è un oggetto, è troppo grande o troppo profondamente nidificato. |
| 422 | unknown_frameworks | Uno o più id di framework non sono presenti nel catalogo (vedi unknown). |
| 429 | rate_limited | Troppe richieste; rallentare. |
| 405 | method_not_allowed | Metodo HTTP non supportato su questo endpoint. |
| 500 | internal | Errore imprevisto del server; riprovare con backoff è sicuro. |
Limiti di frequenza
I limiti di richieste per chiave e per IP proteggono il servizio. Rimani sotto ~1 richiesta/secondo e non riceverai mai un 429. La configurazione è un piano di controllo - la imposti occasionalmente, non in un ciclo continuo.
GET /v1/frameworks
Il catalogo completo leggibile dalla macchina (nessuna autenticazione - punta qui il tuo agente per scoprire gli id validi):
{ "frameworks": [ { "id": "ISO_27001", "name": "ISO 27001:2022", "region": "International" }, … ] }Catalogo dei framework
Il catalogo dei framework di heyGRC viene restituito da GET /v1/frameworks (il conteggio cresce nel tempo; non codificare in modo rigido). Passa l'id canonico in frameworks. Gli id più comuni:
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, e NIS 2 come NIS_2 più varianti per paese (NIS_2_DE, NIS_2_FR, NIS_2_IT, …).
Una PUT con un id al di fuori del catalogo viene rifiutata con 422 unknown_frameworks e gli id non validi vengono restituiti, in modo che il tuo agente possa autocorreggersi.