Referencia de la API

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. Alcance: config:read.

200

{
  "profile": { "company": "Acme Inc", "...": "..." },
  "frameworks": ["ISO_27001", "SOC_2", "GDPR"],
  "eu_inference": false,
  "review_language": "en",
  "commitments": [
    { "area": "logging", "implementation": "nunca registrar correo electrónico ni IP completa", "source": "Política de Registro 4.2" }
  ],
  "commitments_updated_at": "2026-08-26T22:00:00Z"
}

PUT /v1/config

Envía solo lo que deseas cambiar. Cada campo es opcional: un campo omitido mantiene su valor actual, un campo presente se reemplaza. Esto hace que los flujos de trabajo con agentes sean seguros: haz PUT solo del campo que deseas cambiar, sin necesidad de leer-modificar-escribir toda la configuración. Los campos principales desconocidos son rechazados con 400, por lo que un error tipográfico nunca pasará desapercibido. Alcance: config:write.

Encabezados: Content-Type: application/json; opcional Idempotency-Key: <string> (registrado para reintentos seguros).

Cuerpo

200

{ "ok": true, "commitments": [ { "area": "logging", "implementation": "nunca registrar correo electrónico ni IP completa" } ] }

Solo se devuelven los campos que enviaste. Solo se devuelve un 200 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"] } }
| 400 | `invalid_request` | Campo(s) de nivel superior desconocidos, o un cuerpo sin ninguno de los campos conocidos (actualización vacía). |
| 422 | `invalid_commitments` | `commitments` no es un array de filas válidas (área desconocida o duplicada, texto demasiado largo, caracteres de control). `null` es un 400: usa `[]` para borrar. |

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.