Довідник API

Публічний API heyGRC: ендпоінти для фреймворків та налаштування перевірок з формами запитів і відповідей.

Базова URL-адреса: https://api.heygrc.com

Усі запити автентифікуються за допомогою ключа API для організації як Bearer-токен:

Authorization: Bearer hgrc_...

Ключ належить одній організації heyGRC (один на встановлення GitHub App) і має скоупи (config:read, config:write). Надсилайте ключ лише в заголовку - ключі, передані в URL, відхиляються (400), щоб уникнути їх витоку в логи та реферери. Організація, над якою виконується запит, завжди визначається за ключем, тому ключ може читати або змінювати конфігурацію лише своєї організації.

`GET /v1/config`

Повертає поточну конфігурацію вашої організації. Обсяг доступу: 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`

Надішліть лише ті зміни, які хочете внести. Кожне поле є необов’язковим: відсутнє поле зберігає своє поточне значення, а наявне — замінюється. Це робить робочі процеси агента безпечними: надішліть лише те поле, яке хочете змінити, без читання-модифікації-запису всієї конфігурації. Невідомі поля верхнього рівня відхиляються з кодом 400, тому помилка в імені поля ніколи не призведе до безшумного бездіяння. Обсяг доступу: config:write.

Заголовки: Content-Type: application/json; необов’язковий Idempotency-Key: <string> (записується для безпечних повторних спроб).

Тіло запиту

Поле	Тип	Примітки
`profile`	object (необов’язковий)	Вільний контекст компанії. Має бути JSON-об’єктом, ≤ 16 КБ, максимальна глибина вкладеності 4, значення — рядки / числа / булеві / масиви цих типів. Наявне = замінюється; відсутнє = не змінюється.
`frameworks`	string[] (необов’язковий)	Ідентифікатори рамок, яким ви маєте відповідати. Кожен ідентифікатор має бути в каталозі — невідомі ідентифікатори відхиляються, а не безшумно видаляються. Наявне = замінюється; відсутнє = не змінюється.
`commitments`	array (необов’язковий)	Ваші зобов’язання щодо впровадження: до 5 рядків, по одному на область (`logging`, `access_mfa`, `encryption`, `pii_retention`, `subprocessors`); кожен рядок — `{ "area", "implementation" (1-300 символів, один рядок), "source"? (1-120 символів, один рядок) }`. Наявне = замінюється (надішліть `[]`, щоб очистити); відсутнє = не змінюється; `null` відхиляється.
`eu_inference`	boolean (необов’язковий)	Постійне: відсутнє = поточне значення зберігається; булеве = встановлюється. Небулеві значення відхиляються.
`review_language`	string (необов’язковий)	Постійне: відсутнє = не змінюється; один із `en`, `de`, `es`, `fr`, `it`, `nl`, `pl`.

200

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

Повертаються лише ті поля, які ви надіслали. Код 200 повертається лише після того, як зміна і її аудиторський запис успішно збережені разом, тому успішний запис завжди підлягає аудиту.

Помилки

Стабільна структура JSON для кожної помилки:

{ "error": { "code": "unknown_frameworks", "message": "unknown framework ids: FOO", "unknown": ["FOO"] } }
| 400 | `invalid_request` | Невідомі поля верхнього рівня або тіло запиту не містить жодного відомого поля (порожнє оновлення). |
| 422 | `invalid_commitments` | `commitments` не є масивом з дійсними рядками (невідома або дублююча область, надто довгий текст, керуючі символи). `null` призводить до 400: використовуйте `[]` для очищення. |

Статус	`code`	Значення
400	`invalid_request`	Невалідне тіло JSON, неправильна структура тіла або ключ було передано в URL.
401	`unauthorized`	Відсутній, некоректний, недійсний, прострочений або відкликаний ключ.
403	`forbidden`	Ключ не має необхідного скоупу (`config:read` / `config:write`).
422	`invalid_profile`	`profile` не є об'єктом, занадто великий або має занадто глибоку вкладеність.
422	`unknown_frameworks`	Один або кілька ідентифікаторів фреймворків відсутні в каталозі (див. `unknown`).
429	`rate_limited`	Забагато запитів; сповільніться.
405	`method_not_allowed`	HTTP-метод не підтримується на цій кінцевій точці.
500	`internal`	Неочікувана помилка сервера; безпечно повторити із затримкою.

Обмеження швидкості

Обмеження кількості запитів на ключ і IP-адресу захищають сервіс. Дотримуйтеся швидкості приблизно 1 запит/секунду, і ви ніколи не отримаєте 429. Конфігурація - це контрольна площина: ви змінюєте її час від часу, а не в гарячому циклі.

`GET /v1/frameworks`

Повний машинозчитуваний каталог (без автентифікації - вкажіть сюди свій агент для виявлення дійсних ідентифікаторів):

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

Каталог фреймворків

Каталог фреймворків heyGRC повертається за запитом GET /v1/frameworks (кількість зростає з часом; не кодувати жорстко). Передавайте канонічний ідентифікатор у frameworks. Найпоширеніші ідентифікатори:

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, а також NIS 2 як NIS_2 плюс варіанти для окремих країн (NIS_2_DE, NIS_2_FR, NIS_2_IT, …).

Запит PUT з ідентифікатором поза каталогом відхиляється з помилкою 422 unknown_frameworks, а проблемні ідентифікатори повертаються назад, щоб ваш агент міг самостійно виправити помилку.

Довідник API

GET /v1/config

PUT /v1/config