API pública

A API pública v1 é o que o CLI, a GitHub Action e o GitHub App usam. Tudo o que eles fazem, você faz com HTTP puro.

Referência: abra a referência interativa.
Contrato: o arquivo OpenAPI 3 é publicado em /openapi/openapi.yaml. Ele é a fonte da verdade: a referência e os clientes gerados derivam dele, e os testes da própria API falham quando uma rota está faltando nele.

Autenticação

Envie Authorization: Bearer <credencial>, onde a credencial é:

uma chave de API (mg_live_<id>_<segredo>) criada no console, só com os escopos de que você precisa; ou
um token curto da troca OIDC (10 minutos, só no GitHub Actions).

Use GET /v1/whoami para ver qual app, plano e escopos uma credencial tem. É também o que o moatgator whoami chama.

Versionada no caminho (/v1). Toda resposta traz Moatgator-Api-Version. Dentro da v1, as mudanças são aditivas (campos, endpoints, parâmetros opcionais e códigos de erro novos): os clientes devem ignorar os campos que não conhecem. Uma mudança incompatível ganha uma nova versão maior, e a antiga continua funcionando durante um período de depreciação de pelo menos 6 meses, anunciado com os cabeçalhos Deprecation e Sunset. A v1.0 não deprecia nada.
Erros são application/problem+json (RFC 9457) com um code estável e legível por máquina (validation_failed, insufficient_scope, rate_limited…). Erros internos nunca incluem detalhes.
Limites de taxa são por chave de API, conforme o plano do app, em uma janela de 60 segundos. Toda resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset; um 429 traz também Retry-After.
Idempotência: envie um Idempotency-Key nas escritas que você puder repetir.

Estado

A API está construída e testada, mas ainda não foi implantada em api.moatgator.com. Veja a tabela de estado na introdução.