API

Grafana exposes two parallel HTTP APIs:

1. The legacy REST API under /api/* — implemented by handlers in pkg/api/ and grown organically since 2014.
2. The app-platform API under /apis/<group>/<version>/<resource> — Kubernetes-style, generated from CUE schemas in apps/<name>/.

Both are served from the same HTTP server. They typically read/write the same underlying data; the app-platform API is the long-term direction but the legacy API still carries the bulk of traffic.

OpenAPI specs

The REST API is fully described in OpenAPI 2.0:

• public/api-merged.json — full merged spec (OSS + plugins).
• public/api-spec.json — OSS-only.

Regenerate with:

make swagger-gen

The Swagger UI is available at /swagger when running locally.

TypeScript clients

packages/grafana-api-clients/ holds RTK Query clients generated from the merged OpenAPI spec. Regenerate with:

yarn generate-apis

Sub-pages

• REST endpoints — high-level inventory of /api/*.
• App-platform / k8s API — the /apis/* surface.

Authentication

All endpoints require an authenticated identity unless [auth.anonymous] is enabled. Supported authentication methods:

• Session cookie (browser).
• Service account token: Authorization: Bearer <token>.
• API key (legacy).
• Basic auth.
• JWT (with [auth.jwt] configured).
• OAuth (interactive flow only).
• Render token (short-lived, image renderer only).

See Authentication.

Error format

API errors return a JSON body:

{
  "message": "human-readable description",
  "messageId": "errors.dashboard.access-denied",
  "statusCode": 403,
  "traceID": "..."
}

The messageId is a stable string usable for client-side i18n / mapping. The traceID correlates with backend logs / tracing.

Versioning

• The legacy /api/* endpoints are versioned ad-hoc: most are unversioned, alerting uses /api/v1/*, ruler-compatible endpoints follow Prometheus conventions.
• The app-platform API uses Kubernetes-style versioning: each resource has one or more versions (v0alpha1, v1, v2alpha1, …) that coexist on the wire.

Rate limits and quotas

OSS Grafana doesn't enforce rate limits at the framework level, but does enforce quotas (max dashboards per org, max API keys per user, etc.) via pkg/services/quota/. Cloud and Enterprise add additional throttling.