codeDB API

API REST, OAuth 2.0 e servidor MCP do codeDB, a plataforma de monitoramento de SQL Server e PostgreSQL. Somente leitura: listar as instâncias monitoradas e investigar incidentes (lentidão, bloqueios, queda de health score) com causa raiz e evidências. Especificação completa em /openapi.json (OpenAPI 3.1).

Quando usar

Responder "o que aconteceu com o banco ontem às 14h?" ou "por que ficou lento?" com dados reais de incidentes.
Levar incidentes do codeDB para ServiceNow, Jira, Grafana, Zabbix ou um agente de IA.
Inventariar as instâncias SQL Server/PostgreSQL monitoradas e ver se o agente está reportando.

Não serve para executar SQL nem alterar configuração: para um diagnóstico local e pontual, sem conta, use o codeDB Lens (código aberto, também com MCP).

Acesso

Crie uma conta em app.codedb.com.br/auth/register: teste grátis de 7 dias, sem cartão de crédito. No dashboard, em Configurações → API Keys — Integração Pública, clique em Nova API Key e copie a chave (cdb_v1_…, exibida uma única vez). API Keys estão disponíveis nos planos Trial e Business.

Endpoints

URL base: https://api.codedb.com.br. Escopos entre parênteses.

GET /api/v1/incidents?days=7&instance_id=&environment_id= — incidentes com causa raiz (incidents:read).
GET /api/v1/instances — instâncias ativas, engine e último contato do agente (instances:read).

curl -s -H "X-API-Key: $CODEDB_API_KEY" \
  "https://api.codedb.com.br/api/v1/incidents?days=1"

Erros são JSON: { "detail": …, "error": { "code", "message", "hint", "docs" } }, com code estável (unauthorized, forbidden, not_found, validation_error, rate_limited…).

OAuth 2.0 (client_credentials)

Para não trafegar a API Key em toda chamada, troque-a por um access token de 1 hora. client_id é o prefixo da chave (14 primeiros caracteres, mostrado na lista de chaves) e client_secret é a chave completa. Metadata em /.well-known/oauth-authorization-server.

curl -s -X POST https://api.codedb.com.br/oauth/token \
  -d grant_type=client_credentials \
  -d client_id="${CODEDB_API_KEY:0:14}" \
  -d client_secret="$CODEDB_API_KEY"
# → {"access_token": "…", "token_type": "Bearer", "expires_in": 3600, "scope": "…"}

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://api.codedb.com.br/api/v1/instances

Servidor MCP

Endpoint https://api.codedb.com.br/mcp (Model Context Protocol, transporte Streamable HTTP) com as ferramentas read-only list_incidents e list_instances. initialize e tools/list não exigem credencial; tools/call exige Authorization: Bearer + API Key ou access token. Manifesto em /.well-known/mcp/server-card.json.

{
  "mcpServers": {
    "codedb": {
      "type": "http",
      "url": "https://api.codedb.com.br/mcp",
      "headers": { "Authorization": "Bearer cdb_v1_SUA_CHAVE" }
    }
  }
}

claude mcp add --transport http codedb https://api.codedb.com.br/mcp \
  --header "Authorization: Bearer $CODEDB_API_KEY"

Limites de requisição (rate limits)

120 requisições por minuto por IP, somando /api/v1/* e /mcp. Toda resposta informa o limite e o saldo da janela atual, para o cliente se autorregular:

RateLimit-Policy: "default";q=120;w=60   # cota de 120 por janela de 60 s
RateLimit: "default";r=87;t=23           # restam 87; a janela zera em 23 s
X-RateLimit-Limit: 120                   # mesmos valores, convenção X-RateLimit-*
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 23

Os headers RateLimit/RateLimit-Policy seguem o draft IETF httpapi-ratelimit-headers. Ao estourar, a resposta é 429 com error.code = "rate_limited" e Retry-After em segundos: espere esse tempo antes de tentar de novo. POST /oauth/token tem limite próprio de 20 por minuto.

Versionamento e descontinuação (deprecation)

A versão vai na URL: /api/v1. A versão atual é a v1, estável.
Dentro de uma versão só entram mudanças compatíveis: novos endpoints, novos parâmetros opcionais e novos campos na resposta. Ignore campos que você não conhece.
Mudanças incompatíveis (remover ou renomear campo, mudar tipo ou semântica) só saem numa nova versão (/api/v2).
Um endpoint ou uma versão descontinuada passa a responder com os headers Deprecation (RFC 9745) e Sunset (RFC 8594), com a data de desligamento, e um Link: rel="deprecation" para o guia de migração.
Prazo mínimo de 6 meses entre o aviso de descontinuação e o desligamento, com aviso por e-mail aos donos de API Keys ativas. Hoje nenhum endpoint está descontinuado.

Guia completo do produto na documentação; resumo para LLMs em /llms.txt; código aberto em github.com/codedb-io.