Visão Geral da API

A API REST do ChatCLI AIOps Platform fornece acesso programático completo a todas as funcionalidades da plataforma. Construída sobre padrões Kubernetes-like (apiVersion + kind + metadata + spec + status), com autenticação via API key e rate limiting por role.

Incidents

Detecção, ack, snooze, timeline, remediação e resolução

Runbooks

CRUD completo de planos de remediação

Analytics

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

SLOs

Targets, error budget, burn rate e histórico

Federation

Status multi-cluster, correlações cross-tier

Health

Liveness e readiness probes

Base URL

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

A porta padrão é 8090 mas pode ser alterada via Helm (--set apiPort=...) ou env var CHATCLI_API_PORT. Em produção, exponha atrás de um Ingress com TLS.

Fluxo de uma requisição

Autenticação

Todas as requisições devem incluir o header X-API-Key com uma chave válida:

curl -H "X-API-Key: ck_live_abc123" \
  http://operator:8090/api/v1/incidents

import requests

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

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

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

Roles

viewer

Somente leitura. GET em todos os endpoints. Ideal para dashboards e ferramentas de observabilidade.

operator

Operação diária. GET + POST de ações (acknowledge, approve, reject). NOC, SRE e on-call.

admin

Acesso total. GET, POST, PUT, DELETE. CI/CD, automações privilegiadas e ferramentas de gestão.

As chaves de API são configuradas no ConfigMap do operator:

apiVersion: v1
kind: ConfigMap
metadata:
  name: chatcli-operator-config
  namespace: chatcli-system
data:
  api-keys: |
    - key: "ck_live_abc123..."
      role: admin
      description: "CI/CD Pipeline"
    - key: "ck_live_def456..."
      role: operator
      description: "NOC Team"
    - key: "ck_live_ghi789..."
      role: viewer
      description: "Grafana dashboard"

Em ambiente de desenvolvimento, se o ConfigMap chatcli-api-keys não existir, o operator roda em dev mode sem auth — útil para testes locais, nunca em produção.

Rate limiting

Role	Limite	Janela
`viewer`	100 req	por minuto
`operator`	500 req	por minuto
`admin`	1000 req	por minuto

Headers de rate limit retornados em cada resposta:

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 487
X-RateLimit-Reset: 1710864000

Quando o limite é excedido, o operator retorna 429 Too Many Requests com header Retry-After (em segundos). Implemente backoff exponencial em clients de produção.

Formato de resposta

Todas as respostas seguem o padrão Kubernetes-like:

Lista
Recurso individual
Erro

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

{
  "apiVersion": "v1",
  "kind": "Incident",
  "metadata": {
    "name": "INC-20260319-001",
    "namespace": "production",
    "createdAt": "2026-03-19T15:20:00Z"
  },
  "spec":   { "...": "..." },
  "status": { "...": "..." }
}

{
  "apiVersion": "v1",
  "kind": "Error",
  "error": {
    "code": 401,
    "message": "API key inválida ou ausente",
    "details": "Inclua o header X-API-Key com uma chave válida"
  }
}

Códigos de erro

Código	Significado	Quando acontece
`400`	Bad Request	Parâmetros ausentes ou mal formatados
`401`	Unauthorized	`X-API-Key` ausente ou inválida
`403`	Forbidden	Role insuficiente para a operação
`404`	Not Found	Recurso não existe
`409`	Conflict	Recurso já existe ou estado inválido para a operação
`429`	Too Many Requests	Rate limit excedido — veja `Retry-After`
`500`	Internal Server Error	Falha no operator — investigue logs

Paginação

Endpoints que retornam listas suportam paginação via query parameters:

integer

padrão:"1"

Número da página (começa em 1)

integer

padrão:"20"

Itens por página (máximo: 100)

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

A resposta inclui metadata.totalCount para você calcular o número total de páginas.

Versionamento

A API utiliza versionamento via path (/api/v1/). Versões futuras serão adicionadas como /api/v2/ mantendo compatibilidade retroativa com v1.

Mudanças breaking-change só ocorrem entre versões maiores. Dentro de uma versão, apenas adições compatíveis (novos campos opcionais, novos endpoints) são publicadas.

Próximos passos

AIOps Platform — visão geral

Como a plataforma detecta, analisa e remedia incidentes

Operator Kubernetes

Deploy do operator, CRDs e configuração

Incident lifecycle

Fluxo completo: detecção → análise → remediação → resolução

AIOps em produção

Cookbook: setup completo com TLS, RBAC, notificações e SLOs

Introdução

Incidents

AI Insights

Remediations

Runbooks

Approvals

SLOs

PostMortems

Analytics

Clusters

Federation

Audit

Health

Visão Geral da API

Incidents

Runbooks

Analytics

SLOs

Federation

Health

Base URL

Fluxo de uma requisição

Autenticação

Roles

viewer

operator

admin

Rate limiting

Formato de resposta

Códigos de erro

Paginação

Versionamento

Próximos passos

AIOps Platform — visão geral

Operator Kubernetes

Incident lifecycle

AIOps em produção

Incidents

Runbooks

Analytics

SLOs

Federation

Health

​Base URL

​Fluxo de uma requisição

​Autenticação

​Roles

viewer

operator

admin

​Rate limiting

​Formato de resposta

​Códigos de erro

​Paginação

​Versionamento

​Próximos passos

AIOps Platform — visão geral

Operator Kubernetes

Incident lifecycle

AIOps em produção

Base URL

Fluxo de uma requisição

Autenticação

Roles

Rate limiting

Formato de resposta

Códigos de erro

Paginação

Versionamento

Próximos passos