Skip to main content

Public API

The public API v1 is what the CLI, the GitHub Action and the GitHub App use. Everything they do, you can do with plain HTTP.

  • Reference: open the interactive reference.
  • Contract: the OpenAPI 3 file is published at /openapi/openapi.yaml. It is the source of truth: the reference and the generated clients derive from it, and the API's own tests fail when a route is missing from it.

Authentication​

Send Authorization: Bearer <credential>, where the credential is either:

  • an API key (mg_live_<id>_<secret>) created in the console with only the scopes you need; or
  • a short token from the OIDC exchange (10 minutes, GitHub Actions only).

Use GET /v1/whoami to see which app, plan and scopes a credential has. It is also what moatgator whoami calls.

Conventions​

  • Versioned in the path (/v1). Every response carries Moatgator-Api-Version. Within v1, changes are additive (new fields, endpoints, optional parameters, new error codes): clients must ignore fields they do not know. A breaking change gets a new major version, and the old one keeps working during a deprecation period of at least 6 months, announced with Deprecation and Sunset headers. v1.0 deprecates nothing.
  • Errors are application/problem+json (RFC 9457) with a stable machine-readable code (validation_failed, insufficient_scope, rate_limited…). Internal errors never include details.
  • Rate limits are per API key, by the plan of the app, in a 60-second window. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; a 429 also carries Retry-After.
  • Idempotency: send an Idempotency-Key on writes you may retry.
Status

The API is built and tested but not deployed to api.moatgator.com yet. See the state table on the introduction.