Skip to main content
Version: 2.0

REST API Reference

This page maps the KubeOpera REST API by area and shows the most common calls. Each service page has the complete endpoint list, and the OpenAPI descriptions have every request and response schema.

All paths below are relative to your API base URL (https://<your-kubeopera-domain>/api) and require a bearer token — see API Overview.

Endpoints by area​

AreaGateway prefixService reference
Apps, deployments, builds, CloudSpaces, clusters/kubeoperakubeopera-api
Users, roles, tokens, SSO/authauth-service
Health, cost, metrics/k8s-monitork8s-monitor
Security posture/securitySecurity
Pipelines and runs/cicdcicd-gateway
Anomalies and alert rules/anomaliesanomaly-detector
Forecasts and scaling decisions/forecastspredictive-scaler
Incidents and runbooks/incidentsincident-manager
AI pipeline/agents/{observability,analysis,action,feedback,recommendation}AI Agents
Agent runs/agents/runtimeagent-runtime
Logs, traces, APM, SLOs/logs, /traces, /apm, /sloObservability services

Common tasks​

The examples use:

export KO=https://kubeopera.example.com/api
export AUTH="Authorization: Bearer $KUBEOPERA_TOKEN"

Deploy an app​

curl -X POST $KO/kubeopera/api/v1/apps -H "$AUTH" -H "Content-Type: application/json" -d '{
  "name": "hello",
  "cloudspace_id": "b1f0…",
  "source": { "type": "image", "image": "ghcr.io/stefanprodan/podinfo:6.7.0" },
  "port": 9898,
  "resources": { "cpu_request": "100m", "memory_request": "64Mi" },
  "tls": true
}'

Follow it until it's reachable:

curl $KO/kubeopera/api/v1/apps/{id}/deploy-status -H "$AUTH"
# { "phase": "Verifying", "gitops": "Synced", "ready_replicas": 1, "reachable": false }

Scale an app​

curl -X POST $KO/kubeopera/api/v1/apps/{id}/scale -H "$AUTH" \
  -H "Content-Type: application/json" -d '{ "replicas": 3 }'

Roll back an app​

curl $KO/kubeopera/api/v1/apps/{id}/deployments -H "$AUTH"   # revision history
curl -X POST $KO/kubeopera/api/v1/apps/{id}/rollback -H "$AUTH" \
  -H "Content-Type: application/json" -d '{ "revision": 4 }'

Check a cluster's health​

curl $KO/k8s-monitor/api/health -H "$AUTH"
# { "healthScore": 87, "readyNodes": 5, "totalNodes": 5, "issues": [ … ] }

List open incidents​

curl "$KO/incidents/api/v1/incidents?status=open" -H "$AUTH"

Approve a pending action​

curl $KO/agents/action/api/v1/actions/pending -H "$AUTH"
curl -X POST $KO/agents/action/api/v1/actions/{id}/approve -H "$AUTH"

Start an AI investigation and stream it​

RUN=$(curl -s -X POST $KO/agents/runtime/api/v1/runs -H "$AUTH" \
  -H "Content-Type: application/json" -d '{
    "agent_type": "sre_orchestrator",
    "cluster_id": "prod-us-east",
    "prompt": "Why did the health score drop in the last hour?"
  }' | jq -r .run_id)

curl -N $KO/agents/runtime/api/v1/runs/$RUN/stream -H "$AUTH"

Report a CI run​

Pipelines also accept a per-pipeline reporting token, so your CI doesn't need a user token — see Pipelines.

Next steps​