Skip to main content
Version: 2.0

API Overview

Everything you can do in the Tantilium Cloud Runner (TCR) dashboard, you can do programmatically. There are two ways to integrate.

Use the REST API to script TCR or integrate it with your own tools and CI pipelines. Use Webhooks when you want to be notified as things happen: an incident opens, a deploy finishes, an action runs.

Base URL​

All REST calls go through your TCR 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​