Dokumentacja API

Publiczne API heyGRC: endpointy do zarządzania frameworkami i konfiguracją przeglądów, wraz ze strukturami żądań i odpowiedzi.

Adres bazowy: https://api.heygrc.com

Wszystkie żądania uwierzytelniają się za pomocą klucza API dla organizacji, przesyłanego jako token Bearer:

Authorization: Bearer hgrc_...

Klucz należy do jednej organizacji heyGRC (jeden na instalację GitHub App) i posiada zakresy uprawnień (config:read, config:write). Przesyłaj klucz wyłącznie w nagłówku – klucze przekazane w adresie URL są odrzucane (400), aby uniknąć ich wycieku do logów i referrerów. Organizacja, na której działa żądanie, jest zawsze wyprowadzana z klucza, więc klucz może odczytywać lub zapisywać konfigurację wyłącznie swojej organizacji.

`GET /v1/config`

Zwraca bieżącą konfigurację Twojej organizacji. Zakres: 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`

Wyślij tylko to, co zmieniasz. Każde pole jest opcjonalne: pominięte pole zachowuje swoją bieżącą wartość, obecne pole jest zastępowane. Dzięki temu przepływy pracy agentów są bezpieczne: PUT tylko pole, które chcesz zmienić, bez konieczności odczytu-modyfikacji-zapisu całej konfiguracji. Nieznane pola najwyższego poziomu są odrzucane z kodem 400, więc literówka nigdy nie spowoduje bezgłośnego niepowodzenia. Zakres: config:write.

Nagłówki: Content-Type: application/json; opcjonalny Idempotency-Key: <string> (rejestrowany w celu bezpiecznych ponownych prób).

Body

Pole	Typ	Uwagi
`profile`	object (opcjonalny)	Wolny kontekst firmy. Musi być obiektem JSON, ≤ 16 KB, maksymalna głębokość zagnieżdżenia 4, wartości to ciągi znaków / liczby / wartości logiczne / tablice tych typów. Obecne = zastąpione; pominięte = niezmienione.
`frameworks`	string[] (opcjonalny)	Identyfikatory ram, których musisz przestrzegać. Każdy identyfikator musi znajdować się w katalogu — nieznane identyfikatory są odrzucane, nie pomijane bezgłośnie. Obecne = zastąpione; pominięte = niezmienione.
`commitments`	array (opcjonalny)	Twoje zobowiązania wdrożeniowe: maksymalnie 5 wierszy, po jednym dla każdej dziedziny (`logging`, `access_mfa`, `encryption`, `pii_retention`, `subprocessors`); każdy wiersz to `{ "area", "implementation" (1-300 znaków, jeden wiersz), "source"? (1-120 znaków, jeden wiersz) }`. Obecne = zastąpione (wyślij `[]`, aby wyczyścić mapę); pominięte = niezmienione; `null` jest odrzucany.
`eu_inference`	boolean (opcjonalny)	Trwałe: pominięte = zachowaj bieżącą wartość; wartość logiczna = ustaw. Nie-boolean są odrzucane.
`review_language`	string (opcjonalny)	Trwałe: pominięte = niezmienione; jedna z wartości: `en`, `de`, `es`, `fr`, `it`, `nl`, `pl`.

200

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

Zwracane są tylko pola, które wysłałeś. Kod 200 jest zwracany dopiero po tym, jak zmiana i jej rekord audytu zostaną razem zatwierdzone, dzięki czemu udany zapis jest zawsze możliwy do audytu.

Błędy

Stała struktura JSON dla każdego błędu:

{ "error": { "code": "unknown_frameworks", "message": "unknown framework ids: FOO", "unknown": ["FOO"] } }
| 400 | `invalid_request` | Nieznane pola najwyższego poziomu lub ciało zawierające wyłącznie nieznane pola (pusta aktualizacja). |
| 422 | `invalid_commitments` | `commitments` nie jest tablicą poprawnych wierszy (nieznany lub zduplikowany obszar, tekst o nadmiernej długości, znaki sterujące). `null` jest traktowane jako 400: użyj `[]` aby wyczyścić. |

Status	`code`	Znaczenie
400	`invalid_request`	Nieprawidłowe żądanie JSON, niepoprawna struktura treści lub klucz przekazany w adresie URL.
401	`unauthorized`	Brakujący, niepoprawnie sformułowany, nieprawidłowy, przeterminowany lub unieważniony klucz.
403	`forbidden`	Klucz nie posiada wymaganego zakresu (`config:read` / `config:write`).
422	`invalid_profile`	`profile` nie jest obiektem, jest zbyt duży lub zbyt głęboko zagnieżdżony.
422	`unknown_frameworks`	Jeden lub więcej identyfikatorów frameworków nie znajduje się w katalogu (zobacz `unknown`).
429	`rate_limited`	Zbyt wiele żądań; zwolnij tempo.
405	`method_not_allowed`	Metoda HTTP nieobsługiwana w tym punkcie końcowym.
500	`internal`	Nieoczekiwany błąd serwera; można bezpiecznie ponowić z backoffem.

Limity szybkości

Limity żądań na klucz i adres IP chronią usługę. Pozostań poniżej ~1 żądania/sekundę, a nigdy nie zobaczysz 429. Konfiguracja to płaszczyzna kontrolna – ustawiasz ją okazjonalnie, a nie w gorącej pętli.

`GET /v1/frameworks`

Pełny, czytelny maszynowo katalog (bez uwierzytelniania – skieruj tutaj swojego agenta, aby odkryć prawidłowe identyfikatory):

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

Katalog frameworków

Katalog frameworków heyGRC jest zwracany przez GET /v1/frameworks (liczba rośnie z czasem; nie koduj na stałe). Przekazuj kanoniczny identyfikator w polu frameworks. Najczęściej używane identyfikatory:

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, oraz NIS 2 jako NIS_2 wraz z wariantami dla poszczególnych krajów (NIS_2_DE, NIS_2_FR, NIS_2_IT, …).

Żądanie PUT z identyfikatorem spoza katalogu jest odrzucane z kodem 422 unknown_frameworks, a błędne identyfikatory są zwracane, dzięki czemu Twój agent może samodzielnie skorygować błąd.

Dokumentacja API

GET /v1/config

PUT /v1/config