Skip to content
GreenKube

API Reference

The REST API is served by greenkube-api under /api/v1 (and /api/v2 for changes, the ledger and recommendations v2). Interactive documentation and the OpenAPI schema are available at /api/v1/docs and /api/v1/openapi.json. The full reference is docs/api.md.

  • Machines send a scoped API key: Authorization: Bearer gk_<id>_<secret>. Administrators create keys in Settings > API keys or with POST /api/v1/auth/api-keys; the key is shown once. Scopes: read, write, approve, plans:deliver, signals:write, signals:report, metrics:read, admin. A request outside its scopes answers 403 INSUFFICIENT_SCOPE.
  • The dashboard signs in with POST /api/v1/auth/login and uses an HttpOnly session cookie. Mutations authenticated by the cookie need a same-origin Origin and the X-CSRF-Token header returned by GET /api/v1/auth/me.
  • Headless installs (config.apiAuthMode: api_key) have no accounts: the sign-in page posts an API key to POST /api/v1/auth/api-key-login ({"key": "...", "remember": false}), which checks it like a Bearer key and answers with a signed HttpOnly cookie, never the key itself. It accepts the bootstrap key or a scoped key with the read scope, needs HTTPS (or localhost), and lasts 12 hours (30 days with “Keep me signed in”). Revoking the key signs its browsers out.
  • Single sign-on works through an authentication proxy or native OpenID Connect, with IdP groups mapped to the viewer, operator and admin roles.

Unauthenticated requests answer 401. A production instance never serves anonymous requests.

MethodPathDescription
GET/healthReadiness and version; 503 with status: migrating until the schema is current
GET/setup/statusThe setup checklist: capabilities, checks, and the fix for anything missing
GET/configNon-sensitive runtime configuration, including the pricing currency
GET/health/servicesHealth of the configured data sources
MethodPathDescription
GET/recommendations/activeActive and pr_open recommendations with their expected value and delivery eligibility, ranked
GET/recommendations/{id}One recommendation
GET/recommendations/{id}/eventsIts lifecycle audit trail
GET/api/v2/recommendations/{id}The v2 shape: consensus, votes and revisions
GET/recommendations/savingsProjected, run-rate and realized-to-date savings blocks, never summed
GET/recommendations/exportActive recommendations as CSV or JSON
PATCH / DELETE/recommendations/{id}/ignoreIgnore or restore
GET/recommendations/{id}/manualManual mode: the kubectl steps
POST/recommendations/{id}/manual/appliedMark as applied by hand; the change is then measured
POST/optimization/runsQueue a scan for the controller (202)
GET/sourcesEvery source with its status, last run and counts
GET/sources/{id}/runs, /sources/{id}/signalsA source’s runs and signals
GET/sources/track-recordMeasured realization rate per source and capability
POST/signalsPush a signal batch (signals:write)
POST/sources/krr/reportsPush a Robusta KRR JSON report (signals:report)
MethodPathDescription
GET/gitops/status, /gitops/coverageController availability, discovery freshness, binding coverage
GET/gitops/bindingsWorkload bindings (paginated, filterable by status)
POST/gitops/bindings/{namespace}/{kind}/{name}/resolvePick one candidate for an ambiguous binding
GET/automation/statusAutomation readiness
POST/automation/plansCreate a render-validated preview from recommendation ids
GET/automation/plans/{plan_id}The preview with source and rendered diffs
POST/automation/plans/{plan_id}/approveApprove the exact sha256: digest and enqueue the plan (approve scope)
GET/automation/plans/{plan_id}/patchThe approved plan as a git format-patch (patch and CI modes)
POST/automation/plans/{plan_id}/deliveryReport a PR opened outside GreenKube (plans:deliver)
POST/automation/plans/{plan_id}/rollback-previewInverse preview for a change in rollback review
GET/automation/pull-requestsPending and open pull requests
POST/webhooks/{provider_id}Signed GitHub, GitLab or Gitea pull-request events

Changes, measurements and ledger (/api/v2)

Section titled “Changes, measurements and ledger (/api/v2)”
MethodPathDescription
GET/api/v2/changesApplied changes with plan and PR links, generations, digests and latest measurement
GET/api/v2/changes/{id}One change, with its baseline snapshot metadata and whether its content hash still verifies
GET/api/v2/changes/{id}/measurementsDecided measurements: windows, counterfactual parameters, estimates with intervals, confounders, health, capacity
GET/api/v2/ledger/entriesLedger entries, newest first, with their provenance and chain position
GET/api/v2/ledger/summaryOne total per method, quantity and unit (cost, CO₂e, released capacity, cost of fix), plus the chain verification status
GET/api/v2/ledger/exportCSV, or format=focus for FOCUS-aligned rows
MethodPathDescription
GET/metrics/summary, /metrics/timeseries, /metrics/by-namespace, /metrics/top-podsCost, energy and CO₂e per cluster, namespace and pod
GET/nodesNode inventory
GET/report/summaryReport totals; cluster-wide, adds the node idle share and the cluster total
GET/report/exportStream a CSV or JSON report (include_idle=true appends the idle and cluster-total rows)
Terminal window
api() { curl -fsS -H "Authorization: Bearer $GREENKUBE_API_KEY" -H 'Content-Type: application/json' "http://localhost:8000/api/v1$1" "${@:2}"; }
api '/recommendations/active?namespace=shop' # pick recommendation ids
api /automation/plans -X POST -d '{"recommendation_ids":["<id>"]}' # preview: status, digest, diff
api /automation/plans/<plan_id>/approve -X POST -d '{"digest":"sha256:…"}'
api /automation/plans/<plan_id> # pr_open → merged → synced → applied
curl -fsS -H "Authorization: Bearer $GREENKUBE_API_KEY" http://localhost:8000/api/v2/changes

POST /api/v1/sources/polaris/reports answers 404 for every key; nothing is stored. Footprint, recommendation and dashboard series are no longer exported on /prometheus/metrics: read them from /report/summary, /report/export, /metrics/summary, /metrics/dashboard-summary, /nodes and /recommendations instead (Upgrading).