API-Referenz

heyGRC öffentliche API: Endpunkte für Frameworks und Review-Konfiguration mit Anfrage- und Antwortstrukturen.

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

Alle Anfragen authentifizieren sich mit einem organisationsspezifischen API-Schlüssel als Bearer-Token:

Authorization: Bearer hgrc_...

Ein Schlüssel gehört zu einer heyGRC-Organisation (einer pro GitHub-App-Installation) und verfügt über Bereiche (config:read, config:write). Senden Sie den Schlüssel nur im Header – Schlüssel, die in der URL übergeben werden, werden abgelehnt (400), um ein Leaken in Protokolle und Referrer zu vermeiden. Die Organisation, auf die eine Anfrage wirkt, wird immer vom Schlüssel abgeleitet, sodass ein Schlüssel nur die Konfiguration seiner eigenen Organisation lesen oder schreiben kann.

`GET /v1/config`

Gibt die aktuelle Konfiguration Ihrer Organisation zurück. Berechtigung: 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`

Senden Sie nur die zu ändernden Felder. Jedes Feld ist optional: ein weggelassenes Feld behält seinen aktuellen Wert, ein vorhandenes Feld wird ersetzt. Dadurch sind Agenten-Workflows sicher: PUT sendet nur das Feld, das Sie ändern möchten, ohne ein vollständiges Lesen-Ändern-Schreiben der Konfiguration. Unbekannte Felder auf oberster Ebene werden mit 400 abgelehnt, sodass ein Tippfehler nie stumm eine No-Op auslöst. Berechtigung: config:write.

Header: Content-Type: application/json; optionale Idempotency-Key: <string> (für sichere Wiederholungen protokolliert).

Body

Feld	Typ	Hinweise
`profile`	object (optional)	Freiform-Unternehmenskontext. Muss ein JSON-Objekt sein, ≤ 16 KB, maximale Verschachtelungstiefe 4, Werte sind Strings / Zahlen / Booleans / Arrays dieser Typen. Vorhanden = ersetzt; weggelassen = unverändert.
`frameworks`	string[] (optional)	Die Framework-IDs, denen Sie entsprechen müssen. Jede ID muss im Katalog vorhanden sein – unbekannte IDs werden abgelehnt, nicht stumm verworfen. Vorhanden = ersetzt; weggelassen = unverändert.
`commitments`	array (optional)	Ihre Umsetzungsverpflichtungen: bis zu 5 Zeilen, eine pro Bereich (`logging`, `access_mfa`, `encryption`, `pii_retention`, `subprocessors`); jede Zeile ist `{ "area", "implementation" (1-300 Zeichen, eine Zeile), "source"? (1-120 Zeichen, eine Zeile) }`. Vorhanden = ersetzt (senden Sie `[]`, um die Zuordnung zu löschen); weggelassen = unverändert; `null` wird abgelehnt.
`eu_inference`	boolean (optional)	Beständig: weggelassen = aktueller Wert wird beibehalten; Boolean = setzen. Nicht-Booleans werden abgelehnt.
`review_language`	string (optional)	Beständig: weggelassen = unverändert; einer der Werte `en`, `de`, `es`, `fr`, `it`, `nl`, `pl`.

200

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

Es werden nur die Felder zurückgegeben, die Sie gesendet haben. Ein 200 wird erst nach der Änderung und deren Protokollierung zusammen zurückgegeben, sodass eine erfolgreiche Schreiboperation immer nachvollziehbar ist.

Fehler

Stabile JSON-Struktur bei jedem Fehler:

{ "error": { "code": "unknown_frameworks", "message": "unbekannte Framework-IDs: FOO", "unknown": ["FOO"] } }
| 400 | `invalid_request` | Unbekannte Top-Level-Felder oder ein Body ohne bekannte Felder (leere Aktualisierung). |
| 422 | `invalid_commitments` | `commitments` ist kein Array mit gültigen Zeilen (unbekannte oder doppelte Fläche, zu langer Text, Steuerzeichen). `null` führt zu 400: Verwenden Sie `[]` zum Löschen. |

Status	`code`	Bedeutung
400	`invalid_request`	Kein JSON-Body, falsche Body-Struktur oder ein Schlüssel wurde in der URL übergeben.
401	`unauthorized`	Fehlender, falsch formatierter, ungültiger, abgelaufener oder widerrufener Schlüssel.
403	`forbidden`	Dem Schlüssel fehlt der erforderliche Bereich (`config:read` / `config:write`).
422	`invalid_profile`	`profile` ist kein Objekt, zu groß oder zu tief verschachtelt.
422	`unknown_frameworks`	Eine oder mehrere Framework-IDs sind nicht im Katalog enthalten (siehe `unknown`).
429	`rate_limited`	Zu viele Anfragen; verlangsamen Sie das Tempo.
405	`method_not_allowed`	HTTP-Methode wird auf diesem Endpunkt nicht unterstützt.
500	`internal`	Unerwarteter Serverfehler; Wiederholung mit Backoff ist sicher.

Ratenbegrenzung

Pro-Schlüssel- und Pro-IP-Anfragegrenzen schützen den Dienst. Bleiben Sie unter ~1 Anfrage/Sekunde, und Sie werden nie ein 429 sehen. Die Konfiguration ist eine Steuerungsebene – Sie setzen sie gelegentlich, nicht in einer heißen Schleife.

`GET /v1/frameworks`

Der vollständige, maschinenlesbare Katalog (keine Authentifizierung – richten Sie Ihren Agenten hierhin, um gültige IDs zu entdecken):

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

Framework-Katalog

heyGRC kennt den Live-Katalog. Übergeben Sie die kanonische ID in frameworks. Die häufigsten 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, und NIS 2 als NIS_2 sowie länderspezifische Varianten (NIS_2_DE, NIS_2_FR, NIS_2_IT, …).

Eine PUT-Anfrage mit einer ID außerhalb des Katalogs wird mit 422 unknown_frameworks abgelehnt, und die fehlerhaften IDs werden zurückgegeben, sodass Ihr Agent sich selbst korrigieren kann.

API-Referenz

GET /v1/config

PUT /v1/config