API-referentie

heyGRC publieke API: eindpunten voor frameworks en reviewconfiguratie, met request- en responsevormen.

Basis-URL: https://api.heygrc.com

Alle verzoeken authenticeren met een API-sleutel per organisatie als Bearer-token:

Authorization: Bearer hgrc_...

Een sleutel behoort tot één heyGRC-organisatie (één per GitHub App-installatie) en bevat scopes (config:read, config:write). Verstuur de sleutel alleen in de header - sleutels die in de URL worden doorgegeven, worden geweigerd (400), om te voorkomen dat ze in logs en verwijzers terechtkomen. De organisatie waarop een verzoek betrekking heeft, wordt altijd afgeleid van de sleutel, dus een sleutel kan alleen de configuratie van zijn eigen organisatie lezen of schrijven.

`GET /v1/config`

Retourneert de huidige configuratie van jouw organisatie. Scope: 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`

Stuur alleen aan wat je wijzigt. Elk veld is optioneel: een weggelaten veld behoudt de huidige waarde, een aanwezig veld wordt vervangen. Dit maakt agent-workflows veilig: PUT alleen het veld dat je wilt wijzigen, geen lees-wijzig-schrijf van de hele configuratie. Onbekende top-level velden worden afgewezen met 400, dus een typefout leidt nooit tot een stille no-op. Scope: config:write.

Headers: Content-Type: application/json; optioneel Idempotency-Key: <string> (gelogd voor veilige herhalingen).

Body

Veld	Type	Opmerkingen
`profile`	object (optioneel)	Vrije bedrijfscontext. Moet een JSON-object zijn, ≤ 16 KB, maximale nestingdiepte 4, waarden zijn strings / getallen / booleans / arrays daarvan. Aanwezig = vervangen; weggelaten = ongewijzigd.
`frameworks`	string[] (optioneel)	De framework-id's waar je aan moet voldoen. Elke id moet in de catalogus staan - onbekende id's worden afgewezen, niet stilzwijgend verwijderd. Aanwezig = vervangen; weggelaten = ongewijzigd.
`commitments`	array (optioneel)	Jouw implementatieverplichtingen: maximaal 5 regels, één per gebied (`logging`, `access_mfa`, `encryption`, `pii_retention`, `subprocessors`); elke regel is `{ "area", "implementation" (1-300 tekens, één regel), "source"? (1-120 tekens, één regel) }`. Aanwezig = vervangen (stuur `[]` om de map leeg te maken); weggelaten = ongewijzigd; `null` wordt afgewezen.
`eu_inference`	boolean (optioneel)	Vasthoudend: weggelaten = huidige waarde behouden; boolean = instellen. Niet-boolean waarden worden afgewezen.
`review_language`	string (optioneel)	Vasthoudend: weggelaten = ongewijzigd; één van `en`, `de`, `es`, `fr`, `it`, `nl`, `pl`.

200

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

Alleen de velden die je hebt verzonden worden teruggegeven. Een 200 wordt alleen geretourneerd nadat de wijziging en de auditregistratie gezamenlijk zijn vastgelegd, dus een succesvolle schrijfbewerking is altijd controleerbaar.

Fouten

Stabiele JSON-vorm bij elke fout:

{ "error": { "code": "unknown_frameworks", "message": "onbekende framework-ids: FOO", "unknown": ["FOO"] } }
| 400 | `invalid_request` | Onbekend top-level veld(en), of een body zonder bekende velden (lege update). |
| 422 | `invalid_commitments` | `commitments` is geen array met geldige rijen (onbekend of dubbel gebied, tekst te lang, controletekens). `null` is een 400: gebruik `[]` om te wissen. |

Status	`code`	Betekenis
400	`invalid_request`	Geen JSON-body, verkeerde body-vorm, of een sleutel werd in de URL doorgegeven.
401	`unauthorized`	Ontbrekende, misvormde, ongeldige, verlopen of ingetrokken sleutel.
403	`forbidden`	De sleutel heeft niet de vereiste scope (`config:read` / `config:write`).
422	`invalid_profile`	`profile` is geen object, is te groot, of is te diep genest.
422	`unknown_frameworks`	Een of meer framework-ids staan niet in de catalogus (zie `unknown`).
429	`rate_limited`	Te veel verzoeken; vertraag.
405	`method_not_allowed`	HTTP-methode wordt niet ondersteund op dit endpoint.
500	`internal`	Onverwachte serverfout; opnieuw proberen met backoff is veilig.

Snelheidslimieten

Per-sleutel en per-IP-aanvraaglimieten beschermen de service. Blijf onder ongeveer 1 verzoek/seconde en u zult nooit een 429 zien. Configuratie is een control plane - u stelt deze af en toe in, niet in een hot loop.

`GET /v1/frameworks`

De volledige, machineleesbare catalogus (geen authenticatie - wijs uw agent hierheen om geldige ids te ontdekken):

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

Frameworkcatalogus

De frameworkcatalogus van heyGRC wordt geretourneerd door GET /v1/frameworks (het aantal groeit in de loop van de tijd; hardcodeer deze niet). Geef de canonieke id door in frameworks. De meest voorkomende ids:

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, en NIS 2 als NIS_2 plus landvarianten (NIS_2_DE, NIS_2_FR, NIS_2_IT, …).

Een PUT met een id buiten de catalogus wordt geweigerd met 422 unknown_frameworks en de foutieve ids worden teruggegeven, zodat uw agent zichzelf kan corrigeren.

API-referentie

GET /v1/config

PUT /v1/config