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 aktualną konfigurację Twojej organizacji. Wymagany zakres: config:read.

200

{
  "profile": { "company": "Acme Inc", "...": "..." },
  "frameworks": ["ISO_27001", "SOC_2", "GDPR"],
  "eu_inference": false
}

`PUT /v1/config`

Pełne zastąpienie konfiguracji Twojej organizacji. Idempotentne: treść żądania stanowi pełny pożądany stan (wszystko, co pominięto, zostanie usunięte). Wymagany zakres: config:write.

Jeden wyjątek od pełnego zastąpienia: eu_inference jest opcjonalne i trwałe. Pominięcie pozostawia bieżącą wartość organizacji bez zmian; przesłanie wartości logicznej ją ustawia (wartości nielogiczne są odrzucane). Nie polegaj na pomijającym PUT, aby ją zresetować.

Nagłówki: Content-Type: application/json; opcjonalny Idempotency-Key: <string> (logowany w celu bezpiecznego ponawiania żądań).

Treść żądania

Pole	Typ	Uwagi
`profile`	object (wymagane)	Dowolny 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.
`frameworks`	string[] (wymagane)	Identyfikatory frameworków, z którymi musisz być zgodny. Każdy identyfikator musi znajdować się w katalogu – nieznane identyfikatory są odrzucane, a nie cicho pomijane.
`eu_inference`	wartość logiczna (opcjonalna)	Trwałe: pominięte = bieżąca wartość zachowana; wartość logiczna = ustawiona. Wartości nielogiczne są odrzucane.

200

{ "ok": true, "profile": { "...": "..." }, "frameworks": ["ISO_27001", "SOC_2", "GDPR"] }

Odpowiedź 200 jest zwracana dopiero po zatwierdzeniu zarówno zmiany, jak i jej rekordu audytu, więc 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"] } }

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