Riferimento API

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,
  "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

Invia solo ciò che vuoi modificare. Ogni campo è opzionale: un campo omesso mantiene il suo valore attuale, un campo presente viene sostituito. Questo rende i flussi di lavoro degli agenti sicuri: PUT solo il campo che vuoi cambiare, senza leggere-modificare-scrivere l'intera configurazione. I campi di primo livello sconosciuti vengono rifiutati con 400, quindi un errore di battitura non causa mai un no-op silenzioso. Ambito: config:write.

Intestazioni: Content-Type: application/json; opzionale Idempotency-Key: <string> (registrato per i tentativi sicuri).

Body

200

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

Vengono restituiti solo i campi che hai inviato. Un 200 viene restituito solo dopo che la modifica e il suo record di audit sono stati registrati insieme, quindi una scrittura andata a buon fine è sempre tracciabile.

Errori

Forma JSON stabile per ogni errore:

{ "error": { "code": "unknown_frameworks", "message": "id framework sconosciuti: FOO", "unknown": ["FOO"] } }
| 400 | `invalid_request` | Campo/i di primo livello sconosciuti, oppure un corpo con nessuno dei campi noti (aggiornamento vuoto). |
| 422 | `invalid_commitments` | `commitments` non è un array di righe valide (area sconosciuta o duplicata, testo troppo lungo, caratteri di controllo). `null` è un 400: usa `[]` per cancellare. |

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.