API Overview

The ChatCLI AIOps Platform REST API is served by the operator and gives programmatic access to the AIOps resources (Issues, RemediationPlans, AIInsights, Runbooks, ApprovalRequests, SLOs, PostMortems, AuditEvents, ClusterRegistrations and policies). Responses follow Kubernetes-like patterns (apiVersion + kind + metadata/resourceMeta + spec + status), with API key authentication, three roles and a per-client rate limit.

Incidents

Detection, ack, snooze, timeline, remediation, and resolution

Runbooks

Full CRUD for runbooks

Analytics

MTTD, MTTR, trends, top resources, capacity, compliance, cost

SLOs

Targets, error budget, and burn rate

Federation

Multi-cluster status, cross-cluster correlations

Health

Liveness and readiness endpoints

Base URL

http://<operator-host>:8090/api/v1

The API (and the web dashboard at /) listens on the operator pod, port 8090, exposed as port api of the Service chatcli-operator in the operator namespace (chatcli-system by default). It is not served by the Service of an Instance (that one is the gRPC server on 50051).

kubectl -n chatcli-system port-forward svc/chatcli-operator 8090:8090
curl -H "X-API-Key: $KEY" http://localhost:8090/api/v1/incidents

The port comes from the chart value api.port (default 8090), which sets the CHATCLI_AIOPS_PORT environment variable of the operator. To serve HTTPS (TLS 1.3 minimum), set CHATCLI_AIOPS_TLS_CERT and CHATCLI_AIOPS_TLS_KEY to certificate and key files inside the operator container (chart: security.apiTLS.certFile / security.apiTLS.keyFile). The operator chart has no extraVolumes value, so the files must be provided by another means (for example a patched Deployment); alternatively terminate TLS at an Ingress or gateway in front of the Service. Without both variables the API is plain HTTP.

Multiple operator replicas. Every replica serves the REST API and the dashboard on 8090, so a Service with several replicas can route a request to any pod. Reads are answered by any replica; a manual resolve accepted by a replica that is not the leader is completed by the leader’s Issue reconciler.

Request flow

Authentication

All /api/ requests must include the X-API-Key header with a valid key:

curl -H "X-API-Key: $CHATCLI_API_KEY" \
  http://localhost:8090/api/v1/incidents

import os
import requests

resp = requests.get(
    "http://localhost:8090/api/v1/incidents",
    headers={"X-API-Key": os.environ["CHATCLI_API_KEY"]},
)
incidents = resp.json()["items"]

req, _ := http.NewRequest("GET", "http://localhost:8090/api/v1/incidents", nil)
req.Header.Set("X-API-Key", os.Getenv("CHATCLI_API_KEY"))
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

const resp = await fetch("http://localhost:8090/api/v1/incidents", {
  headers: { "X-API-Key": process.env.CHATCLI_API_KEY },
});
const { items } = await resp.json();

Roles

Roles are ordered viewer < operator < admin; each endpoint requires a minimum role (see the endpoint table). These three strings are the only valid roles: a key with any other role (for example superadmin or readonly) is accepted as a key but gets 403 on every endpoint.

viewer

Read-only. Every GET endpoint. Ideal for dashboards and observability tools.

operator

Daily ops. Everything viewer can do, plus the POST actions (acknowledge, snooze, resolve, approve, reject, postmortem review/close/feedback) and runbook create/update.

admin

Full access. Everything operator can do, plus DELETE /runbooks/{name}.

Configuring API keys

Keys are read from the operator namespace (chatcli-system by default), in this order:

Secret chatcli-operator-secrets, key api-keys (recommended)
ConfigMap chatcli-operator-config, key api-keys (fallback, used only when the Secret does not exist)

The value is a YAML list of {key, role, name, description} entries. name is optional: it is the identity recorded on the approval decisions the key takes (falling back to description, then to a key-<hash> fingerprint), and a quorum counts each key once, so give each approver their own key. The operator chart renders the Secret only with apiKeys.create: true (the keys are then stored in the Helm release); otherwise you create it:

apiVersion: v1
kind: Secret
metadata:
  name: chatcli-operator-secrets
  namespace: chatcli-system
type: Opaque
stringData:
  api-keys: |
    - key: "<random-admin-key>"
      role: admin
      description: "CI/CD pipeline"
    - key: "<random-operator-key>"
      role: operator
      name: "oncall-sre"
      description: "On-call team"
    - key: "<random-viewer-key>"
      role: viewer
      description: "Grafana dashboard"

# Generate a key
openssl rand -hex 32

The operator polls the Secret and ConfigMap every 30 seconds and hot-reloads the keys without a restart: adding or removing an entry takes effect within about 30 s.

No keys configured = every /api/ call returns 401. If neither object holds a valid key, the API is closed (fail-closed). Setting CHATCLI_OPERATOR_DEV_MODE=true on the operator (chart: security.devMode: true) instead lets every request through as admin without a key — for local development only, never in production. Any boolean-true value counts (true, TRUE, 1, t, case-insensitive), for the auth check, the rate limiter and the startup log alike.Keys follow their source: an empty list leaves no valid key, a Secret without an api-keys entry falls back to the ConfigMap, and deleting both the Secret and the ConfigMap revokes every loaded key on the next poll (within about 30 s, 401 from then on). An api-keys entry that is not valid YAML keeps the last valid key set in force and is logged once per version. A read error other than not found also keeps the keys in force, so neither a typo nor an API server hiccup locks everyone out. Startup applies the same rules as the poll.

Try it without a cluster. From the operator/ directory of the repository, make dash-preview serves the dashboard and this API over synthetic data at http://127.0.0.1:8085/ with the API key preview (admin role). Override the address with DASHPREVIEW_ADDR.

Rate limiting

The API allows 30 requests per minute per client host for requests that carry no valid API key (token bucket, bursts of up to 30, refilled continuously at 0.5 req/s), and 600 requests per minute per valid API key (bursts of up to 600, refilled at 10 req/s), keyed by a digest of the key. The limit runs before authentication; the per-key limit is the same for every role. Forwarding headers are not honored, so behind a proxy every unauthenticated caller shares the proxy’s host bucket. Idle buckets are evicted after 10 minutes. When it is exceeded the operator returns 429 Too Many Requests with the standard error envelope (rate limit exceeded: N requests per minute) and a Retry-After header with the seconds until the bucket holds a token again (2 for the host limit, 1 for the key limit). No X-RateLimit-* headers are sent. Implement backoff in production clients, and keep dashboards or scrapers that poll many endpoints within the budget.

CORS

Cross-origin browser requests are denied by default: no CORS headers are sent until an origin is configured. Configure it with environment variables on the operator (or the matching chart values under security.*):

Variable	Chart value	Meaning
`CHATCLI_CORS_ALLOWED_ORIGINS`	`security.corsAllowedOrigins` (list)	Comma-separated allowed origins, or `*`
`CHATCLI_CORS_ORIGIN`	`security.corsOrigin`	A single allowed origin (added to the list)
`CHATCLI_CORS_ALLOWED_METHODS`	`security.corsAllowedMethods`	Allowed methods (default `GET, POST, PUT, DELETE, OPTIONS`)
`CHATCLI_CORS_ALLOW_CREDENTIALS`	`security.corsAllowCredentials`	`true` to allow credentials

Allowed request headers are Content-Type, X-API-Key and Authorization; preflight responses are cached for 1 hour. The dashboard served by the operator itself is same-origin and needs no CORS configuration.

Response format

All responses follow a Kubernetes-like pattern:

List
Single resource
Error

{
  "apiVersion": "v1",
  "kind": "IncidentList",
  "metadata": {
    "totalCount": 42,
    "page": 1,
    "pageSize": 20
  },
  "items": [
    { "...": "..." }
  ]
}

{
  "apiVersion": "v1",
  "kind": "Incident",
  "spec":   { "...": "..." },
  "status": { "...": "..." },
  "resourceMeta": {
    "name": "api-server-oomkilled-8f2c1",
    "namespace": "production",
    "uid": "5b2d7c1e-3f4a-4e8b-9c6d-1a2b3c4d5e6f",
    "creationTimestamp": "2026-03-19T15:20:00Z",
    "labels": {},
    "annotations": {}
  }
}

Which of spec, status and resourceMeta are present depends on the endpoint; each endpoint page shows its exact shape. Empty fields are omitted.

{
  "apiVersion": "v1",
  "kind": "Error",
  "error": "Unauthorized",
  "code": 401,
  "message": "missing API key in X-API-Key header"
}

error is the HTTP status text, code the HTTP status, message the detail.

Error codes

Code	Meaning	When it happens
`400`	Bad Request	Malformed JSON body or invalid/missing body field
`401`	Unauthorized	`X-API-Key` missing or invalid, or no keys configured
`403`	Forbidden	Role below the endpoint’s minimum, an unknown role, or the operator’s RBAC does not allow creating the runbook
`404`	Not Found	Resource does not exist, or unknown path/method combination
`405`	Method Not Allowed	Non-GET request to a read-only group (`analytics`, `clusters`, `policies`, `audit`, `federation`)
`409`	Conflict	Invalid state for the operation (for example resolving an already resolved incident, or deciding on an approval request that is no longer `Pending` or that the same API key already decided), a concurrent modification, or creating a runbook whose name already exists
`422`	Unprocessable Entity	The Kubernetes API server rejected a runbook being created (for example a value outside the CRD enums)
`429`	Too Many Requests	Rate limit exceeded — see `Retry-After`
`500`	Internal Server Error	Kubernetes API failure — inspect the operator logs

Pagination

List endpoints support pagination via query parameters:

integer

default:"1"

Page number (starts at 1)

integer

default:"20"

Items per page (values above 100 are capped at 100)

curl -H "X-API-Key: $KEY" \
  "http://localhost:8090/api/v1/incidents?page=2&pageSize=50"

The response includes metadata.totalCount so you can compute the total number of pages. Invalid values fall back to the defaults. Most lists accept namespace (omitted = all namespaces). Incidents, postmortems, audit events and the analytics endpoints also accept the time filters from / to (RFC 3339, for example 2026-03-19T00:00:00Z), applied to the resource’s creation time (the event time for audit). Unparseable times are ignored.

Endpoints

All paths are relative to /api/v1.

Method	Path	Min role
GET	`/incidents`, `/incidents/{name}`	viewer
GET	`/incidents/{name}/timeline`, `/incidents/{name}/remediation`	viewer
POST	`/incidents/{name}/acknowledge`, `/snooze`, `/resolve`	operator
GET	`/aiinsights`, `/aiinsights/{name}`	viewer
GET	`/remediations`, `/remediations/{name}`	viewer
GET	`/runbooks`, `/runbooks/{name}`	viewer
POST	`/runbooks`	operator
PUT	`/runbooks/{name}`	operator
DELETE	`/runbooks/{name}`	admin
GET	`/approvals`, `/approvals/{name}`	viewer
POST	`/approvals/{name}/approve`, `/approvals/{name}/reject`	operator
GET	`/slos`, `/slos/{name}`, `/slos/{name}/budget`	viewer
GET	`/postmortems`, `/postmortems/{name}`	viewer
POST	`/postmortems/{name}/review`, `/close`, `/feedback`, `/ack-human-action`	operator
GET	`/analytics/summary`, `mttd`, `mttr`, `trends`, `top-resources`, `remediation-stats`, `compliance`, `capacity`, `cost`	viewer
GET	`/clusters`, `/clusters/global-status`, `/clusters/{name}`	viewer
GET	`/policies/{approval\|notification\|escalation\|sla}`, `/policies/{kind}/{name}`	viewer
GET	`/federation`, `/federation/status`, `/federation/clusters`, `/federation/correlations`	viewer
GET	`/audit`, `/audit/export`	viewer

/healthz and /readyz (outside /api/v1) need no key — see Health endpoints.

Versioning

The API uses path-based versioning (/api/v1/). Only v1 exists today.

Next steps

AIOps Platform overview

How the platform detects, analyzes, and remediates incidents

Kubernetes Operator

Operator deployment, CRDs, and configuration

Incident lifecycle

Full flow: detection → analysis → remediation → resolution

AIOps in production

Cookbook: full setup with TLS, RBAC, notifications, and SLOs

Get started

Documentation

Incidents

Runbooks

Analytics

SLOs

Federation

Health

Base URL

Request flow

Authentication

Roles

viewer

operator

admin

Configuring API keys

Rate limiting

CORS

Response format

Error codes

Endpoints

Versioning

Next steps

AIOps Platform overview

Kubernetes Operator

Incident lifecycle

AIOps in production

Incidents

Runbooks

Analytics

SLOs

Federation

Health

​Base URL

​Request flow

​Authentication

​Roles

viewer

operator

admin

​Configuring API keys

​Rate limiting

​CORS

​Response format

​Error codes

​Pagination

​Endpoints

​Versioning

​Next steps

AIOps Platform overview

Kubernetes Operator

Incident lifecycle

AIOps in production

Base URL

Request flow

Authentication

Roles

Configuring API keys

Rate limiting

CORS

Response format

Error codes

Pagination

Endpoints

Versioning

Next steps