Referência da API REST

A API do HeroCtl é o canal único entre você, o CLI e a interface web. Tudo que o painel mostra passa por aqui. Tudo que o heroctl faz na linha de comando também.

A API é REST. JSON na entrada, JSON na saída. Sem GraphQL. Sem gRPC público.

Endpoint base

https://manage.<seu-dominio>/v1/

Em produção padrão: https://manage.heroctl.com/v1/.

Todas as rotas vivem sob /v1/. Quando o v2 chegar, o v1 continua respondendo por pelo menos 12 meses.

Autenticação

A API usa JWT. Você obtém um token via login e envia em cada requisição:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Sem header, sem resposta. O servidor responde 401.

Login

curl -X POST https://manage.heroctl.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

Resposta:

{
  "token": "eyJhbGciOi...",
  "expires_at": "2026-04-27T15:00:00Z",
  "refresh_token": "rt_8f3a..."
}

O token padrão dura 24 horas.

Você também pode autenticar com um ACL token (gerado pela interface ou pelo CLI):

curl -X POST https://manage.heroctl.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"acl_token":"ht_a1b2c3d4..."}'

Refresh

Antes do token expirar, troque por um novo:

curl -X POST https://manage.heroctl.com/v1/auth/refresh \
  -H "Authorization: Bearer $TOKEN"

Endpoints principais

Jobs

Um job é a definição declarativa do que deve rodar. O cluster cuida do resto.

Listar jobs:

curl -s https://manage.heroctl.com/v1/jobs \
  -H "Authorization: Bearer $TOKEN" | jq '.[] | .name'

Submeter um job:

curl -X POST https://manage.heroctl.com/v1/jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @meu-job.json

Allocations

Cada réplica de um job vira uma allocation. É a unidade de execução real.

curl -s "https://manage.heroctl.com/v1/allocations?job=heroctl-site" \
  -H "Authorization: Bearer $TOKEN" | jq '.[] | {id, node, status}'

Nodes

Os servidores que rodam workloads.

Drenar um nó antes de manutenção:

curl -X POST https://manage.heroctl.com/v1/nodes/server-2/drain \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"deadline_seconds": 300}'

Atenção: drain remove todas as allocations do nó. Garanta capacidade nos demais antes.

Cluster

curl -s https://manage.heroctl.com/v1/cluster/status \
  -H "Authorization: Bearer $TOKEN" | jq

Secrets

Valores sensíveis. Armazenados criptografados em repouso.

Criar um secret:

curl -X POST https://manage.heroctl.com/v1/secrets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"db_password","value":"s3nh@-forte"}'

Métricas

curl -s "https://manage.heroctl.com/v1/metrics/query?metric=cpu&job=heroctl-site&from=-1h" \
  -H "Authorization: Bearer $TOKEN" | jq

Logs

Logs vivem por allocation.

Streaming ao vivo:

curl -N "https://manage.heroctl.com/v1/logs?job=heroctl-site&stream=true" \
  -H "Authorization: Bearer $TOKEN"

A saída vem em formato text/event-stream:

event: log
data: {"alloc":"a1b2","line":"server started"}

Health

Endpoints sem autenticação. Para uso de monitoramento externo.

curl -s https://manage.heroctl.com/v1/health/ready
# {"status":"ok"}

Ingress

Domínios servidos pelo cluster.

curl -s https://manage.heroctl.com/v1/ingress/heroctl.com \
  -H "Authorization: Bearer $TOKEN" | jq

Long polling

Vários endpoints suportam espera bloqueante. Em vez de fazer poll a cada segundo, você passa um índice e o tempo máximo de espera. A resposta volta quando algo muda — ou quando o tempo acaba.

curl -s "https://manage.heroctl.com/v1/jobs?wait=5m&index=42" \
  -H "Authorization: Bearer $TOKEN"

• index=N — índice da última versão que você viu.
• wait=5m — tempo máximo de espera (máximo 10m).

Se nada mudar em 5 minutos, a resposta vem com o mesmo índice. Reusa-se o índice na próxima chamada.

Isso reduz tráfego e latência drasticamente em painéis ao vivo.

Rate limiting

Cada token tem um limite de 1000 requisições por minuto. Acima disso o servidor responde:

HTTP/1.1 429 Too Many Requests
Retry-After: 12

O header Retry-After indica em segundos quando você pode tentar de novo.

Tokens admin têm limite separado e mais generoso. Para automação pesada, peça um token de serviço dedicado.

Códigos de erro

Erros vêm com corpo padronizado:

{
  "error": "job_not_found",
  "message": "job 'foo' não existe",
  "request_id": "req_a1b2c3"
}

Sempre inclua o request_id quando abrir um chamado de suporte.

Webhooks (Plano Business)

Você registra uma URL e o cluster envia POSTs em eventos relevantes.

curl -X POST https://manage.heroctl.com/v1/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "url": "https://api.minha-empresa.com/heroctl-events",
    "events": ["job.deployed", "alloc.failed", "node.down"],
    "secret": "whk_a1b2c3"
  }'

Eventos disponíveis:

• job.submitted — novo job enviado
• job.deployed — todas as réplicas saudáveis
• job.failed — deploy falhou e fez rollback
• alloc.failed — uma instância caiu
• node.down — um servidor saiu do cluster
• cert.renewed — certificado TLS renovado
• secret.changed — valor de secret atualizado

Cada POST traz um header X-HeroCtl-Signature com HMAC-SHA256 do corpo, usando o secret que você registrou. Valide antes de processar.

Próximos passos

• Veja autenticação e ACL para criar tokens com escopo restrito.
• Veja troubleshooting se uma chamada estiver retornando erros inesperados.
• Veja backup e restore para proteger o estado que a API expõe.