Pular para o conteúdo
Documentação

API do miniProxy

Como autenticar na API REST do miniProxy e referência dos endpoints de domínios, certificados, backends, portas TCP e Blocklist, com exemplos curl.

R Regis Manze 20/11/2026 14 min de leitura

A API REST do miniProxy permite automatizar, a partir de outro sistema, as mesmas tarefas que você faz pelo painel: publicar um domínio, apontá-lo para um backend, gerar o certificado SSL, adicionar ou tirar servidores e bloquear IPs. É ela que o miniCP usa para publicar os sites de um servidor no balanceador da frente.

Todas as respostas são em JSON e todas as alterações de configuração são aplicadas com reload do HAProxy na mesma chamada.

URL base

Todos os endpoints ficam sob o caminho /haproxy-admin/api. A URL completa depende de como o painel está publicado:

Forma de acesso URL base
Direto na porta do painel (padrão 5000) http://203.0.113.10:5000/haproxy-admin/api
Pelo domínio do painel, atrás do HAProxy em HTTPS https://proxy.exemplo.com.br/haproxy-admin/api

Atenção: prefira sempre o acesso por HTTPS. Na autenticação Basic o usuário e a senha viajam em cada requisição; em HTTP puro eles passam abertos pela rede. Não publique a porta 5000 direto na internet: libere o acesso ao painel só para os IPs dos sistemas que usam a API.

Autenticação

A API usa HTTP Basic Auth com um usuário e senha do próprio painel (os mesmos da tela de login). Não há token de API separado.

Para criar um usuário só para a integração:

  1. Vá em Sistema > Usuarios.
  2. Clique em Novo Usuario.
  3. Preencha Usuario (ex.: integracao-minicp) e Senha (mínimo 6 caracteres) e clique em Criar.
  4. Use esse usuário e senha no sistema que vai chamar a API.

Com curl, informe as credenciais com -u:

curl -u integracao-minicp:SENHA https://proxy.exemplo.com.br/haproxy-admin/api/version

Detalhes importantes:

  • Sem credenciais válidas, a resposta é 401 com {"ok": false, "error": "Autenticacao necessaria"}.
  • Chamadas com Basic Auth não passam pela verificação de origem (proteção CSRF) do painel, então funcionam a partir de qualquer script ou servidor.
  • Os endpoints de gráficos e telas internas do painel (lista no fim desta página) não aceitam Basic Auth: só funcionam com a sessão de quem está logado no navegador.

Dica: se você trocar a senha do usuário em Usuarios > Alterar senha, atualize também a configuração do sistema integrado (no miniCP, a aba HAProxy em Configuracoes).

Formato das requisições e respostas

  • Envie o corpo dos POST em JSON, com o cabeçalho Content-Type: application/json.
  • Toda resposta traz "ok": true ou "ok": false. Em caso de erro, o campo error explica o motivo e o status HTTP indica o tipo (400 dado inválido, 404 não encontrado, 409 já existe, 500 falha ao executar).
  • Nas operações que alteram a config, o campo reload diz se o reload do HAProxy deu certo ("ok") ou traz a mensagem de falha.

Antes de gravar, a maioria das operações valida a nova configuração com o HAProxy; se ela for recusada, nada é alterado e a resposta traz o erro. A cada alteração o painel guarda um backup do haproxy.cfg, que pode ser restaurado em Sistema > Backups.

Versão

GET /version

Retorna a versão do miniProxy instalada. Útil para conferir se vários servidores estão na mesma versão.

curl -u integracao-minicp:SENHA https://proxy.exemplo.com.br/haproxy-admin/api/version
{"version": "2.36.1"}

Provisionar um site completo

POST /provision

Faz em uma única chamada as três etapas de publicar um site: cria o backend com os servidores, cria o domínio apontando para ele e gera o certificado SSL.

Campo O que informar
domain Domínio principal (obrigatório), ex.: loja.exemplo.com.br
servers Lista de servidores (obrigatório): name, address, port e, opcionais, maxconn (padrão 3000) e backup (padrão false)
backend Nome do backend. Se omitido, é gerado a partir do domínio (ex.: bk_loja_exemplo_com_br)
balance Algoritmo de balanceamento (padrão roundrobin)
include_www Incluir também o www. (padrão true)
generate_cert Gerar o certificado SSL (padrão true)
email Email para o Let's Encrypt. Opcional se o Email do responsavel estiver preenchido em Configs > Geral do painel
curl -u integracao-minicp:SENHA -X POST \
  https://proxy.exemplo.com.br/haproxy-admin/api/provision \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "loja.exemplo.com.br",
    "servers": [{"name": "web1", "address": "198.51.100.20", "port": 80}]
  }'

A resposta mostra o resultado de cada etapa em steps (backend, domain e cert):

{
  "ok": true,
  "domain": "loja.exemplo.com.br",
  "backend": "bk_loja_exemplo_com_br",
  "steps": {
    "backend": {"ok": true, "name": "bk_loja_exemplo_com_br", "servers": 1, "reload": "ok"},
    "domain": {"ok": true, "acl_name": "loja_exemplo_com_br", "backend": "bk_loja_exemplo_com_br", "reload": "ok"},
    "cert": {"ok": true, "pem_path": "/etc/haproxy/certs/loja.exemplo.com.br.pem", "reload": "ok"}
  }
}

Comportamento quando algo já existe:

  • Backend já existe: a etapa backend é pulada ("skipped": true) e os servidores enviados não são aplicados. Para mudar os servidores de um backend existente, use /backends/add-server e /backends/remove-server.
  • Domínio já existe: ele é atualizado no lugar (veja /domains/add abaixo) e a resposta traz "updated": true.
  • Certificado: se a etapa falhar (DNS não aponta para o proxy, domínio atrás da Cloudflare com proxy ligado etc.), backend e domínio continuam criados; a resposta volta com "ok": false e o erro do certbot em steps.cert.error.

Atenção: o certificado é emitido pela validação HTTP-01, então o domínio precisa já estar apontando para este proxy. Domínios com proxy da Cloudflare ligado (nuvem laranja) devem usar a validação DNS-01 em Certificados SSL.

Domínios

GET /domains

Lista os domínios publicados no frontend HTTPS, com seus hosts e backend.

curl -u integracao-minicp:SENHA https://proxy.exemplo.com.br/haproxy-admin/api/domains

POST /domains/add

Cria um domínio apontando para um backend que já existe. Se o domínio já existir, ele é atualizado no lugar (upsert): os hosts novos são somados aos atuais, o backend é trocado e a resposta traz "updated": true. Isso permite usar a mesma chamada para "trocar o backend do domínio".

Campo O que informar
domain Domínio (obrigatório)
backend Backend de destino. Se omitido, usa o backend padrão do frontend. Precisa existir, senão a chamada é recusada
include_www Incluir também o www. (padrão true)
acl_name Nome interno do domínio na config. Se omitido, é gerado a partir do domínio (pontos e hífens viram _)
curl -u integracao-minicp:SENHA -X POST \
  https://proxy.exemplo.com.br/haproxy-admin/api/domains/add \
  -H "Content-Type: application/json" \
  -d '{"domain": "loja.exemplo.com.br", "backend": "bk_servidor2"}'
{"ok": true, "updated": true, "domain": "loja.exemplo.com.br", "acl_name": "loja_exemplo_com_br",
 "backend": "bk_servidor2", "include_www": true, "reload": "ok"}

Na config, o resultado é um par de linhas no frontend ft_https:

acl loja_exemplo_com_br hdr(host) -i loja.exemplo.com.br www.loja.exemplo.com.br
use_backend bk_servidor2 if loja_exemplo_com_br

Dica: se você enviar sempre o mesmo domain sem acl_name, o nome interno gerado é o mesmo, e a chamada atualiza o domínio existente em vez de criar outro. Se um domínio foi criado com um acl_name diferente, envie esse mesmo acl_name.

POST /domains/remove

Remove o domínio (as linhas acl e use_backend). Informe o nome interno, não o domínio.

Campo O que informar
acl_name Nome interno do domínio (obrigatório), como aparece em GET /domains
curl -u integracao-minicp:SENHA -X POST \
  https://proxy.exemplo.com.br/haproxy-admin/api/domains/remove \
  -H "Content-Type: application/json" \
  -d '{"acl_name": "loja_exemplo_com_br"}'

O certificado e o backend não são removidos junto.

Certificados SSL

GET /certs

Lista os certificados instalados no HAProxy, com validade.

curl -u integracao-minicp:SENHA https://proxy.exemplo.com.br/haproxy-admin/api/certs

POST /certs/generate

Gera (ou expande, se já existir) um certificado Let's Encrypt pela validação HTTP-01 e publica no HAProxy.

Campo O que informar
domain Domínio (obrigatório)
include_www Incluir também o www. (padrão true)
email Email para o Let's Encrypt. Opcional se o Email do responsavel estiver preenchido em Configs
curl -u integracao-minicp:SENHA -X POST \
  https://proxy.exemplo.com.br/haproxy-admin/api/certs/generate \
  -H "Content-Type: application/json" \
  -d '{"domain": "loja.exemplo.com.br"}'

A chamada pode levar até cerca de 2 minutos. Configure o timeout do seu cliente HTTP de acordo.

POST /certs/renew

Renova todos os certificados que estão perto de vencer e publica os renovados no HAProxy. Não tem corpo.

curl -u integracao-minicp:SENHA -X POST https://proxy.exemplo.com.br/haproxy-admin/api/certs/renew

A resposta traz certbot_ok (se o certbot terminou sem erro), published (certificados atualizados) e failed (os que falharam). Uma falha em um certificado não impede a publicação dos demais. Pode levar alguns minutos.

POST /certs/remove

Remove um arquivo de certificado do HAProxy. O default.pem não pode ser removido.

Campo O que informar
filename Nome do arquivo, ex.: loja.exemplo.com.br.pem
curl -u integracao-minicp:SENHA -X POST \
  https://proxy.exemplo.com.br/haproxy-admin/api/certs/remove \
  -H "Content-Type: application/json" \
  -d '{"filename": "loja.exemplo.com.br.pem"}'

Backends e servidores

GET /backends

Lista todos os backends com seus servidores.

curl -u integracao-minicp:SENHA https://proxy.exemplo.com.br/haproxy-admin/api/backends

POST /backends/create

Cria um backend novo. Se já existir um com o mesmo nome, a resposta é 409.

Campo O que informar
name Nome do backend (letras, números, - e _), ex.: bk_loja
servers Lista de servidores: name, address, port, e opcionais maxconn e backup
balance Algoritmo (padrão roundrobin)
options Lista de linhas extras da config, ex.: ["option httpchk GET /health"]
curl -u integracao-minicp:SENHA -X POST \
  https://proxy.exemplo.com.br/haproxy-admin/api/backends/create \
  -H "Content-Type: application/json" \
  -d '{
    "name": "bk_loja",
    "servers": [
      {"name": "web1", "address": "198.51.100.20", "port": 80},
      {"name": "web2", "address": "198.51.100.21", "port": 80, "backup": true}
    ]
  }'

POST /backends/add-server

Adiciona um servidor a um backend existente.

Campo O que informar
backend Nome do backend (obrigatório)
name Nome do servidor (obrigatório)
address IP ou hostname (obrigatório)
port Porta (obrigatório)
maxconn Máximo de conexões simultâneas (padrão 3000)
backup true para só receber tráfego quando os principais caírem (padrão false)
curl -u integracao-minicp:SENHA -X POST \
  https://proxy.exemplo.com.br/haproxy-admin/api/backends/add-server \
  -H "Content-Type: application/json" \
  -d '{"backend": "bk_loja", "name": "web3", "address": "198.51.100.22", "port": 80}'

POST /backends/remove-server

Remove um servidor do backend.

curl -u integracao-minicp:SENHA -X POST \
  https://proxy.exemplo.com.br/haproxy-admin/api/backends/remove-server \
  -H "Content-Type: application/json" \
  -d '{"backend": "bk_loja", "name": "web3"}'

POST /backends/toggle-server

Coloca um servidor em manutenção (disable) ou o devolve ao balanceamento (enable). Vale na hora, sem reload, e fica gravado na config.

Campo O que informar
backend Nome do backend
name Nome do servidor
action enable ou disable
curl -u integracao-minicp:SENHA -X POST \
  https://proxy.exemplo.com.br/haproxy-admin/api/backends/toggle-server \
  -H "Content-Type: application/json" \
  -d '{"backend": "bk_loja", "name": "web1", "action": "disable"}'

Atenção: um backend pode atender vários domínios. Desabilitar ou remover o único servidor ativo tira todos esses sites do ar.

POST /backends/remove

Remove um backend inteiro e as linhas use_backend que apontavam para ele. O backend padrão do frontend não pode ser removido.

curl -u integracao-minicp:SENHA -X POST \
  https://proxy.exemplo.com.br/haproxy-admin/api/backends/remove \
  -H "Content-Type: application/json" \
  -d '{"name": "bk_loja"}'

Atenção: os domínios que usavam esse backend passam a cair no backend padrão.

Portas TCP

Equivalente à tela Portas TCP: encaminha uma porta dedicada (MySQL, FTP, SSH...) direto para um servidor, sem HTTP.

GET /tcp-proxies

curl -u integracao-minicp:SENHA https://proxy.exemplo.com.br/haproxy-admin/api/tcp-proxies

POST /tcp-proxies/create

Campo O que informar
name Nome do proxy, ex.: mysql
ports Porta ou intervalos: 3306 ou 21,30000-30010
servers Lista de servidores: name, address, port
bind_addr Endereço de escuta (padrão *, todos)
balance roundrobin, leastconn, source ou first (padrão roundrobin)
timeout Tempo máximo de conexão ociosa (padrão 1h)
curl -u integracao-minicp:SENHA -X POST \
  https://proxy.exemplo.com.br/haproxy-admin/api/tcp-proxies/create \
  -H "Content-Type: application/json" \
  -d '{"name": "mysql", "ports": "3306", "servers": [{"name": "db1", "address": "198.51.100.30", "port": 3306}]}'

Portas já em uso ou reservadas pelo proxy são recusadas com 409.

POST /tcp-proxies/remove

curl -u integracao-minicp:SENHA -X POST \
  https://proxy.exemplo.com.br/haproxy-admin/api/tcp-proxies/remove \
  -H "Content-Type: application/json" \
  -d '{"name": "mysql"}'

Blocklist global

Equivalente a Regras > Blocklist global. Vale para todos os domínios e é aplicada na hora, sem reload.

/blocklist/ip (GET, POST, DELETE)

Método Efeito
GET Lista os IPs/faixas bloqueados, com motivo e data
POST Bloqueia um IP ou faixa CIDR. Campos: ip (obrigatório) e reason (opcional)
DELETE Desbloqueia. Campo: ip
# bloquear
curl -u integracao-minicp:SENHA -X POST \
  https://proxy.exemplo.com.br/haproxy-admin/api/blocklist/ip \
  -H "Content-Type: application/json" \
  -d '{"ip": "203.0.113.45", "reason": "scanner de vulnerabilidades"}'

# desbloquear
curl -u integracao-minicp:SENHA -X DELETE \
  https://proxy.exemplo.com.br/haproxy-admin/api/blocklist/ip \
  -H "Content-Type: application/json" \
  -d '{"ip": "203.0.113.45"}'

O IP bloqueado tem a conexão TCP recusada antes mesmo do TLS, então ele não aparece no log de acesso. Faixas da Cloudflare e de rede interna (privada/loopback) são recusadas pela API, porque derrubariam todo o tráfego que passa por elas.

/blocklist/ua (GET, POST, DELETE)

Bloqueia (403) qualquer requisição cujo User-Agent contenha o trecho informado, sem diferenciar maiúsculas de minúsculas.

Campo O que informar
ua Trecho do User-Agent, sem espaços, até 200 caracteres, ex.: ahrefsbot
reason Motivo (opcional)
curl -u integracao-minicp:SENHA -X POST \
  https://proxy.exemplo.com.br/haproxy-admin/api/blocklist/ua \
  -H "Content-Type: application/json" \
  -d '{"ua": "ahrefsbot", "reason": "crawler de SEO"}'

Atenção: um trecho curto demais (ex.: bot) pega também Googlebot e Bingbot e pode tirar seus sites do Google. Use o nome completo do robô.

Limpar o cache de um domínio

Para domínios com cache ligado em Cache e persistencia, o próprio domínio responde a um caminho especial que limpa o cache dele na hora, sem reload. Use o token exibido na tela Cache e persistencia (botão Trocar token gera outro).

curl -X POST https://loja.exemplo.com.br/__mp-cache-purge -H "X-Purge-Token: TOKEN"

A resposta é cache limpo (200) ou token invalido (403). Cada chamada limpa só o domínio do endereço chamado (incluindo o www.). Esse caminho não usa o usuário e senha do painel.

Endpoints internos do painel

Os endpoints abaixo alimentam as telas e gráficos do painel. Eles exigem a sessão de quem está logado no navegador, não aceitam Basic Auth e podem mudar entre versões sem aviso. Não use em integrações.

Endpoint Usado em
/status, /traffic, /history/*, /server-stats, /tcp-server-stats Dashboard, Backends, Portas TCP
/logs, /logs/tail, /domain-logs Logs e detalhe do domínio
/analytics/*, /ip-traffic Tráfego por domínio, Tráfego & limites
/cache/stats Cache e persistencia
/rules/matches, /rules/log, /blocklog/* Regras e Bloqueios
/waf/*, /threats/check WAF e Listas de ameaças
/health, /diagnostics Saúde (uptime) e Diagnóstico
/ip/info, /ip/log Investigar IP
/update/check, /update/status Atualização

Veja também

Copiar para usar com IA

Este artigo foi útil?

Que bom! O que ajudou mais? O que faltou nesta página?

Opcional — seu voto já foi registrado.

Obrigado pelo seu feedback!