Referencia de la API
API pública de heyGRC: endpoints para marcos de trabajo y configuración de revisiones, con formas de solicitud y respuesta.
URL base: https://api.heygrc.com
Todas las solicitudes se autentican con una clave API por organización como token Bearer:
Authorization: Bearer hgrc_...Una clave pertenece a una organización de heyGRC (una por instalación de GitHub App) y tiene ámbitos (config:read, config:write). Envía la clave solo en el encabezado; las claves pasadas en la URL son rechazadas (400) para evitar que se filtren en registros y referentes. La organización sobre la que actúa una solicitud siempre se deriva de la clave, por lo que una clave solo puede leer o escribir la configuración de su propia organización.
GET /v1/config
Devuelve la configuración actual de tu organización. Ámbito: config:read.
200
{
"profile": { "company": "Acme Inc", "...": "..." },
"frameworks": ["ISO_27001", "SOC_2", "GDPR"],
"eu_inference": false
}PUT /v1/config
Reemplazo completo de la configuración de tu organización. Idempotente: el cuerpo es el estado deseado completo (cualquier cosa que omitas se borra). Ámbito: config:write.
Una excepción al reemplazo completo: eu_inference es opcional y persistente. Omitirlo deja el valor actual de la organización sin cambios; enviar un booleano lo establece (los no booleanos se rechazan). No cuentes con un PUT que lo omita para restablecerlo.
Encabezados: Content-Type: application/json; opcional Idempotency-Key: <string> (registrado para reintentos seguros).
Cuerpo
| Campo | Tipo | Notas |
|---|---|---|
profile | objeto (requerido) | Contexto de la empresa de forma libre. Debe ser un objeto JSON, ≤ 16 KB, profundidad máxima de anidamiento 4, valores son cadenas / números / booleanos / arrays de estos. |
frameworks | string[] (requerido) | Los identificadores de marcos de trabajo con los que debes cumplir. Cada identificador debe estar en el catálogo: los identificadores desconocidos son rechazados, no se eliminan silenciosamente. |
eu_inference | booleano (opcional) | Persistente: omitido = se conserva el valor actual; booleano = se establece. Los no booleanos se rechazan. |
200
{ "ok": true, "profile": { "...": "..." }, "frameworks": ["ISO_27001", "SOC_2", "GDPR"] }Un 200 solo se devuelve después de que el cambio y su registro de auditoría se confirman juntos, por lo que una escritura exitosa siempre es auditables.
Errores
Forma JSON estable en cada error:
{ "error": { "code": "unknown_frameworks", "message": "identificadores de marcos de trabajo desconocidos: FOO", "unknown": ["FOO"] } }| Estado | code | Significado |
|---|---|---|
| 400 | invalid_request | Cuerpo no JSON, forma incorrecta del cuerpo o una clave fue pasada en la URL. |
| 401 | unauthorized | Clave faltante, malformada, inválida, caducada o revocada. |
| 403 | forbidden | La clave carece del ámbito requerido (config:read / config:write). |
| 422 | invalid_profile | profile no es un objeto, es demasiado grande o está demasiado anidado. |
| 422 | unknown_frameworks | Uno o más identificadores de marcos de trabajo no están en el catálogo (ver unknown). |
| 429 | rate_limited | Demasiadas solicitudes; reduce la velocidad. |
| 405 | method_not_allowed | Método HTTP no admitido en este endpoint. |
| 500 | internal | Error inesperado del servidor; es seguro reintentar con backoff. |
Límites de tasa
Los límites de solicitudes por clave y por IP protegen el servicio. Mantente por debajo de ~1 solicitud/segundo y nunca verás un 429. La configuración es un plano de control: la estableces ocasionalmente, no en un bucle activo.
GET /v1/frameworks
El catálogo completo legible por máquina (sin autenticación: apunta tu agente aquí para descubrir identificadores válidos):
{ "frameworks": [ { "id": "ISO_27001", "name": "ISO 27001:2022", "region": "International" }, … ] }Catálogo de marcos de trabajo
heyGRC conoce el catálogo en vivo de trabajo. Pasa el identificador canónico en frameworks. Los identificadores más comunes:
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, y NIS 2 como NIS_2 más variantes por país (NIS_2_DE, NIS_2_FR, NIS_2_IT, …).
Una solicitud PUT con un identificador fuera del catálogo es rechazada con 422 unknown_frameworks y los identificadores problemáticos se devuelven, para que tu agente pueda autocorregirse.