Skip to main content
Version: 2.0

API Overview

Everything you can do in the KubeOpera dashboard, you can do programmatically. There are two ways to integrate:

UseWhen you want to…
REST APIScript KubeOpera or integrate it with your own tools and CI pipelines.
WebhooksBe notified when something happens — an incident opens, a deploy finishes, an action runs.

Base URL​

All REST calls go through your KubeOpera address's API gateway:

https://<your-kubeopera-domain>/api

The gateway routes each path to the right service — for example /api/kubeopera/* to kubeopera-api and /api/incidents/* to incident-manager — and applies authentication, authorization and rate limits consistently. You never need individual service addresses.

Authentication​

Authenticate with a personal access token:

  1. In the dashboard, open Settings → Access Tokens and select New token.
  2. Give it a name, an expiry and the scopes it needs.
  3. Copy the token — it's shown only once.

Send it as a bearer token:

curl -H "Authorization: Bearer $KUBEOPERA_TOKEN" \
  https://kubeopera.example.com/api/kubeopera/api/v1/apps
ScopeAllows
readRead everything the user can see.
deployCreate, change and delete apps, CloudSpaces and pipelines.
actionsApprove and reject actions and scaling decisions; drain, roll back, scale.
agentsStart and cancel agent runs.
adminPlatform and tenant administration (administrators only).

A token acts with the permissions of the user who created it, limited to its scopes. For server-to-server integrations, create a service account in Settings → Service Accounts and use the OAuth2 client-credentials flow:

curl -X POST https://kubeopera.example.com/api/auth/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=$CLIENT_ID -d client_secret=$CLIENT_SECRET \
  -d scope="read deploy"

Conventions​

  • JSON request and response bodies, UTF-8.

  • Timestamps in RFC 3339 UTC (2026-09-26T14:02:31Z).

  • IDs are UUIDs unless stated otherwise.

  • Pagination — list endpoints accept limit and cursor, and return:

    { "data": [ … ], "next_cursor": "eyJpZCI6…", "total": 128 }

  • Errors — a non-2xx response has a consistent body:

    { "error": { "code": "not_found", "message": "App 'hello' was not found.", "request_id": "req_7Hc2…" } }

    Include request_id when you report a problem.

  • Tenancy — tenant users only ever see their own tenant's data; the tenant comes from the token, never from a parameter.

Rate limits​

Each token has a request budget per minute. Every response includes:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 587
X-RateLimit-Reset: 1790000000

When you exceed it you receive 429 Too Many Requests with a Retry-After header.

OpenAPI​

Every service publishes an OpenAPI 3 description at /openapi.json through the gateway (for example /api/kubeopera/openapi.json). Use it to generate a client in your language, or browse it interactively at /api/docs.

Next steps​