API REST

A API do DIVZ fica em https://api.divz.com.br e autentica por chave Bearer que começa com divz_. Com ela você cria projetos, abre branches, roda SQL, instala extensões e gerencia roles sem abrir o console.

Autenticação

Gere uma chave no console, em Configurações → API keys. Ela aparece uma única vez, começa com divz_ e vai no cabeçalho Authorization:

terminal

curl https://api.divz.com.br/api/v1/projects \
  -H "Authorization: Bearer divz_sua_chave_aqui"

A chave herda o dono: ela só enxerga os projetos da conta que a criou. Não existe chave que veja projeto de outra conta.

Escopos

Escopo	Pode	Use quando
READ	só leitura: qualquer GET e consultas SQL, um comando por vez, sem receber connection string	dashboards, monitoramento, um agente que só consulta
READ_WRITE	leitura e escrita nos seus projetos (padrão)	automação de CI, scripts de deploy
ADMIN	tudo, incluindo gerenciar outras chaves	só quando for realmente necessário

Uma chave ADMIN é equivalente a superadmin e alcança rotas administrativas. Trate-a como senha-mestra: não coloque em CI, não compartilhe, e prefira READ_WRITE para automação.

Chaves aceitam validade (expiresInDays) na criação. Uma chave com prazo é melhor que uma chave eterna que ninguém lembra de revogar.

Rotas principais

Base: https://api.divz.com.br. Tudo devolve JSON. Erros vêm com o código HTTP adequado e um corpo {"error": "..."} em português.

Projetos

Método e rota	O que faz
`GET /api/v1/projects`	lista seus projetos com status, região e connection string
`POST /api/v1/projects`	cria um projeto; volta em PROVISIONING e fica ACTIVE em ~1 min
`PATCH /api/v1/projects/:id`	renomeia
`DELETE /api/v1/projects/:id`	arquiva o projeto
`GET /api/v1/projects/:id/stats`	tamanho, nº de tabelas, conexões, cache hit ratio
`GET /api/v1/projects/:id/activity`	trilha de auditoria: quem mexeu em quê
`POST /api/v1/projects/:id/query`	roda SQL e devolve as linhas

Branches e recuperação

Método e rota	O que faz
`GET /api/v1/projects/:id/branches`	lista os branches com LSN e tamanho
`POST /api/v1/projects/:id/branches`	cria branch copy-on-write
`DELETE /api/v1/projects/:id/branches/:bid`	apaga um branch
`POST /api/v1/pitr`	restaura um instante para um branch novo

Roles e acesso

Método e rota	O que faz
`GET /api/v1/projects/:id/roles`	lista roles com as connection strings (devolve segredos)
`POST /api/v1/projects/:id/roles/app`	cria o role de aplicação, que respeita RLS
`POST /api/v1/projects/:id/roles/app/rotate`	rotação suave da senha do role de app
`POST /api/v1/projects/:id/credentials/rotate`	rotaciona a senha do dono (quebra strings antigas)
`GET /api/v1/projects/:id/ip-allow`	lê a allowlist de IPs
`PUT /api/v1/projects/:id/ip-allow`	substitui a allowlist (não acrescenta)

Extensões e migração

Método e rota	O que faz
`GET /api/v1/projects/:id/extensions`	extensões instaladas e disponíveis
`POST /api/v1/projects/:id/extensions`	instala uma extensão da allowlist
`POST /api/v1/migrations/test-connection`	testa a string de origem antes de migrar
`POST /api/v1/migrations`	importa um banco externo para um projeto
`GET /api/v1/migrations/:id`	acompanha o progresso da importação

Exemplo: criar projeto e conectar

bash

KEY="divz_sua_chave_aqui"

# 1. cria
ID=$(curl -s -X POST https://api.divz.com.br/api/v1/projects \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"name": "meu-app"}' | jq -r .id)

# 2. espera ficar ACTIVE (leva cerca de um minuto)
until [ "$(curl -s https://api.divz.com.br/api/v1/projects \
  -H "Authorization: Bearer $KEY" | jq -r ".[] | select(.id==\"$ID\") | .status")" = "ACTIVE" ]; do
  sleep 5
done

# 3. pega a connection string
curl -s https://api.divz.com.br/api/v1/projects \
  -H "Authorization: Bearer $KEY" | jq -r ".[] | select(.id==\"$ID\") | .connectionString"

Limites e disponibilidade

A API está nos planos Pro e Business.
Rotas que criam recurso são limitadas por taxa — a criação de branches, por exemplo, aceita 20 chamadas por minuto. Ao receber 429, espere antes de repetir.
Cotas de plano respondem 402, com a mensagem dizendo qual limite estourou.
O estado do serviço fica em api.divz.com.br/health, aberto e sem autenticação.

Próximo: Servidor MCP (Claude, Cursor)