API de Gerenciamento

O PrimeForge expõe uma API REST (/api/v1) para automatizar o que você faria no painel: consultar sites, servidores, deploys e backups; disparar deploys da sua esteira de CI; e — com a permissão certa — reiniciar um site, acionar o Modo de Pânico, ler e escrever o .env, rodar comandos e criar backups.

A especificação completa fica em /api/v1/openapi.json (OpenAPI 3.1, pública): importe-a no Postman, Insomnia, Bruno ou num gerador de client.

Autenticação e permissões

Toda requisição leva uma API Key no cabeçalho Authorization: Bearer pf_…. As chaves são criadas em Configurações › API e integrações › Chaves de API (botão Criar chave de API) e valem para a organização em que foram criadas.

Modal Criar chave de API, com as permissões Leitura, Deploy e Gerenciar

Cada chave nasce com permissões (abilities) escolhidas na criação — no painel, Leitura, Deploy e Gerenciar:

Permissão O que libera
read Toda leitura (sempre incluída).
deploy POST /sites/{id}/deploy.
manage Reiniciar, Panic Mode, .env, comandos e criação de backups.

Uma chave nunca faz mais do que quem a criou pode fazer no painel: além da permissão, cada ação exige o papel do dono da chave na organização (deploy, .env, comandos, backups e pânico pedem Developer ou acima; leitura vale para qualquer membro). Chaves criadas antes das permissões existirem continuam exatamente como eram (read + deploy). Se o dono sair da organização, a chave para de funcionar na hora.

GET /api/v1/me mostra a chave, suas permissões, a organização e o papel do dono — útil para diagnosticar um 403.

Limites, paginação e erros

  • 60 requisições por minuto por chave (X-RateLimit-Limit / X-RateLimit-Remaining; 429 ao exceder).
  • Listagens aceitam ?page= e ?per_page= (1–100, padrão 25) e devolvem data (lista) mais meta (current_page, last_page, per_page, total).
  • Erros vêm como {"error": "…"}: 401 chave ausente/inválida/expirada, 403 sem permissão ou sem papel, 404 recurso de outra organização ou inexistente, 412 pré-condição (termos de backup, armazenamento), 422 estado ou validação, 423 site em pânico, 429 limite, 502 o servidor recusou a operação.

Endpoints

Método Endpoint Permissão Descrição
GET /me read A chave e seu contexto
GET /sites read Lista os sites (?server_id= filtra)
GET /sites/{id} read Detalhes de um site
GET /sites/{id}/deployments read Deploys, do mais novo ao mais antigo
POST /sites/{id}/deploy deploy Enfileira um deploy (202 + deployment_id)
GET /deployments/{id} read Status e log completo de um deploy
GET /sites/{id}/workers read Processos (Horizon / pools / daemons), filas e jobs com falha (?fresh=1 sonda o servidor)
GET /sites/{id}/certificate read O certificado que o vhost serve (emissor, validade)
POST /sites/{id}/restart manage Reinicia os processos do site
POST /sites/{id}/panic manage Ativa o Modo de Pânico ({"reason": "…"} opcional)
DELETE /sites/{id}/panic manage Desativa o Modo de Pânico
GET /sites/{id}/env manage Lê o .env compartilhado
PUT /sites/{id}/env manage Substitui o .env ({"content": "…"}) e limpa o cache de config
GET /sites/{id}/commands read Últimos comandos rodados no site
POST /sites/{id}/commands manage Roda um comando ({"command": "php artisan about"}) — mesma lista fixa de binários da página Comandos
GET /sites/{id}/commands/{cmd} manage Status, código de saída e saída capturada — a saída pode conter segredos (php artisan config:show database), por isso pede manage e papel Developer ou acima, como rodar o comando
GET /sites/{id}/backups read Backups do site
POST /sites/{id}/backups manage Cria um backup ({"password": "…", "components": [...]}) — a senha nunca é guardada
GET /backups read Todos os backups da organização
GET /backups/{id} read Detalhes, incluindo a URL de download quando disponível
GET /servers read Lista os servidores
GET /servers/{id} read Detalhes de um servidor
GET /servers/{id}/metrics read A amostra mais recente do agente (CPU, memória, disco, rede)

Exemplos

Disparar um deploy e acompanhar até terminar:

DEPLOY=$(curl -s -X POST https://seu-painel.exemplo.com/api/v1/sites/SITE_ID/deploy \
  -H "Authorization: Bearer $PRIMEFORGE_TOKEN" | jq -r .data.deployment_id)

until curl -s https://seu-painel.exemplo.com/api/v1/deployments/$DEPLOY \
  -H "Authorization: Bearer $PRIMEFORGE_TOKEN" | jq -e '.data.status | IN("succeeded","failed","skipped")' >/dev/null; do
  sleep 5
done

Rodar um comando artisan e ler a saída:

CMD=$(curl -s -X POST https://seu-painel.exemplo.com/api/v1/sites/SITE_ID/commands \
  -H "Authorization: Bearer $PRIMEFORGE_TOKEN" -H "Content-Type: application/json" \
  -d '{"command":"php artisan about"}' | jq -r .data.id)

curl -s https://seu-painel.exemplo.com/api/v1/sites/SITE_ID/commands/$CMD \
  -H "Authorization: Bearer $PRIMEFORGE_TOKEN" | jq -r .data.output

Acionar o Modo de Pânico a partir de um alerta externo:

curl -X POST https://seu-painel.exemplo.com/api/v1/sites/SITE_ID/panic \
  -H "Authorization: Bearer $PRIMEFORGE_TOKEN" -H "Content-Type: application/json" \
  -d '{"reason":"Alerta do WAF"}'

Trate as API Keys como segredos: nunca as comite no Git e prefira armazená-las nos "secrets" da sua ferramenta de CI. Se um token vazar, revogue-o na lista e gere outro. Dê a cada automação a menor permissão que ela precisa — uma esteira de deploy não precisa de manage.

Próximos passos

Equipe e Conta Assinatura e Planos