Referência da API

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,
  "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

Envie apenas o que deseja alterar. Todos os campos são opcionais: um campo omitido mantém seu valor atual, um campo presente é substituído. Isso torna os fluxos de trabalho do agente seguros: PUT apenas o campo que deseja alterar, sem leitura-modificação-gravação de toda a configuração. Campos de nível superior desconhecidos são rejeitados com 400, então um erro de digitação nunca resultará em uma operação silenciosa sem efeito. Escopo: config:write.

Headers: Content-Type: application/json; Idempotency-Key: <string> opcional (registrado para tentativas seguras).

Corpo

200

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

Apenas os campos enviados são retornados. Um 200 é retornado somente após a alteração e seu registro de auditoria serem confirmados juntos, então uma gravação 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"] } }
| 400 | `invalid_request` | Campo(s) de nível superior desconhecido(s), ou um corpo sem nenhum dos campos conhecidos (atualização vazia). |
| 422 | `invalid_commitments` | `commitments` não é um array de linhas válidas (área desconhecida ou duplicada, texto muito longo, caracteres de controle). `null` é um 400: use `[]` para limpar. |

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.