Visão Geral da API

API REST do ChatCLI AIOps Platform — incidents, SLOs, runbooks, aprovações, postmortems, analytics, auditoria, federation e health.

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

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

​

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

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

Recurso individual

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

Erro

{
  "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:

page · integer · padrão: "1"

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

pageSize · 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