Довідник 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
}PUT /v1/config
Повна заміна конфігурації вашої організації. Ідемпотентний: тіло запиту є повним бажаним станом (все, що пропущено, буде очищено). Скоуп: config:write.
Один виняток із повної заміни: eu_inference є необов'язковим і стійким. Якщо його пропустити, поточне значення організації залишається незмінним; надсилання булевого значення встановлює його (небулеві значення відхиляються). Не покладайтеся на PUT без цього поля, щоб скинути його.
Заголовки: Content-Type: application/json; необов'язковий Idempotency-Key: <string> (записується для безпечного повторення).
Тіло запиту
| Поле | Тип | Примітки |
|---|---|---|
profile | object (обов'язковий) | Довільний контекст компанії. Має бути об'єктом JSON, ≤ 16 КБ, максимальна глибина вкладеності 4, значення - рядки / числа / булеві значення / масиви цих типів. |
frameworks | string[] (обов'язковий) | Ідентифікатори фреймворків, яких ви повинні дотримуватися. Кожен ідентифікатор має бути в каталозі - невідомі ідентифікатори відхиляються, а не мовчки пропускаються. |
eu_inference | булеве (необов'язкове) | Стійке: пропущено = поточне значення зберігається; булеве = встановлюється. Небулеві значення відхиляються. |
200
{ "ok": true, "profile": { "...": "..." }, "frameworks": ["ISO_27001", "SOC_2", "GDPR"] }Відповідь 200 повертається лише після того, як зміна та її запис аудиту зафіксовані разом, тому успішний запис завжди можна перевірити.
Помилки
Стабільна структура JSON для кожної помилки:
{ "error": { "code": "unknown_frameworks", "message": "unknown framework ids: FOO", "unknown": ["FOO"] } }| Статус | 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, а проблемні ідентифікатори повертаються назад, щоб ваш агент міг самостійно виправити помилку.