Referência da API
API pública heyGRC: endpoints para frameworks e configuração de revisão, com formatos de requisição e resposta.
URL Base: https://api.heygrc.com
Todas as requisições autenticam com uma chave de API por organização como um token Bearer:
Authorization: Bearer hgrc_...Uma chave pertence a uma organização heyGRC (uma por instalação do GitHub App) e carrega escopos (config:read, config:write). Envie a chave apenas no cabeçalho - chaves passadas na URL são rejeitadas (400), para evitar vazamento em logs e referrers. A organização em que uma requisição atua é sempre derivada da chave, portanto, uma chave só pode ler ou escrever a configuração de sua própria organização.
GET /v1/config
Retorna a configuração atual da sua organização. Escopo: config:read.
200
{
"profile": { "company": "Acme Inc", "...": "..." },
"frameworks": ["ISO_27001", "SOC_2", "GDPR"],
"eu_inference": false
}PUT /v1/config
Substituição completa da configuração da sua organização. Idempotente: o corpo é o estado desejado completo (qualquer coisa omitida é apagada). Escopo: config:write.
Uma exceção à substituição completa: eu_inference é opcional e persistente. Omiti-lo mantém o valor atual da organização inalterado; enviar um booleano o define (não booleanos são rejeitados). Não conte com um PUT que o omita para redefini-lo.
Cabeçalhos: Content-Type: application/json; opcional Idempotency-Key: <string> (registrado para retentativas seguras).
Corpo
| Campo | Tipo | Notas |
|---|---|---|
profile | objeto (obrigatório) | Contexto livre da empresa. Deve ser um objeto JSON, ≤ 16 KB, profundidade máxima de aninhamento 4, valores são strings / números / booleanos / arrays desses tipos. |
frameworks | string[] (obrigatório) | Os ids dos frameworks com os quais você deve estar em conformidade. Cada id deve estar no catálogo - ids desconhecidos são rejeitados, não são descartados silenciosamente. |
eu_inference | booleano (opcional) | Persistente: omitido = valor atual mantido; booleano = definido. Não booleanos são rejeitados. |
200
{ "ok": true, "profile": { "...": "..." }, "frameworks": ["ISO_27001", "SOC_2", "GDPR"] }Um 200 só é retornado após a alteração e seu registro de auditoria serem confirmados juntos, portanto, uma escrita bem-sucedida é sempre auditável.
Erros
Formato JSON estável em todos os erros:
{ "error": { "code": "unknown_frameworks", "message": "ids de frameworks desconhecidos: FOO", "unknown": ["FOO"] } }| Status | code | Significado |
|---|---|---|
| 400 | invalid_request | Corpo não JSON, formato incorreto do corpo ou uma chave foi passada na URL. |
| 401 | unauthorized | Chave ausente, malformada, inválida, expirada ou revogada. |
| 403 | forbidden | A chave não possui o escopo necessário (config:read / config:write). |
| 422 | invalid_profile | profile não é um objeto, é muito grande ou está muito aninhado. |
| 422 | unknown_frameworks | Um ou mais ids de frameworks não estão no catálogo (veja unknown). |
| 429 | rate_limited | Muitas requisições; reduza a velocidade. |
| 405 | method_not_allowed | Método HTTP não suportado neste endpoint. |
| 500 | internal | Erro inesperado do servidor; é seguro repetir com backoff. |
Limites de taxa
Limites de requisições por chave e por IP protegem o serviço. Mantenha-se abaixo de ~1 requisição/segundo e você nunca verá um 429. A configuração é um plano de controle - você a define ocasionalmente, não em um loop intenso.
GET /v1/frameworks
O catálogo completo e legível por máquina (sem autenticação - aponte seu agente aqui para descobrir ids válidos):
{ "frameworks": [ { "id": "ISO_27001", "name": "ISO 27001:2022", "region": "International" }, … ] }Catálogo de frameworks
O catálogo de frameworks da heyGRC é retornado por GET /v1/frameworks (a contagem cresce com o tempo; não codifique valores fixos). Passe o id canônico em frameworks. Os ids mais comuns:
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, e NIS 2 como NIS_2 mais variantes por país (NIS_2_DE, NIS_2_FR, NIS_2_IT, …).
Uma requisição PUT com um id fora do catálogo é rejeitada com 422 unknown_frameworks e os ids problemáticos são ecoados de volta, para que seu agente possa se autocorrigir.