Docs/ Referência da API/ Início Rápido

Início Rápido da API

Faça sua primeira chamada à API do sh0 em poucos minutos: crie uma chave de API, liste suas apps, reimplante uma e leia os formatos de resposta.

Note

A API é servida pelo seu painel sh0, no domínio dele depois que você definir um; caso contrário, na porta 9000 do servidor. Todo caminho começa com /api/v1. Os exemplos usam https://panel.example.com: substitua pelo seu próprio endereço.

Criar uma chave de API

No painel, abra Configurações → Chaves API, crie uma chave com o nível de acesso necessário e copie-a: ela só é mostrada uma vez. Os níveis de acesso são explicados em Autenticação da API. Depois guarde-a numa variável de ambiente:

Terminal

export SH0_TOKEN="sh0_..."

Warning

Trate a chave como uma senha: guarde-a num cofre de segredos ou numa variável de ambiente, nunca num repositório. Revogue-a em Configurações → Chaves API assim que ela possa ter vazado.

Passo 2: Listar Seus Apps

Liste suas aplicações. Qualquer nível de acesso permite isso:

Terminal

curl https://panel.example.com/api/v1/apps \
  -H "Authorization: Bearer $SH0_TOKEN"

Reimplantar uma app

Dispare uma nova implantação de uma app existente, usando o ID dela na lista. É preciso o nível Implantação ou Administração. O corpo pode ser vazio, mas deve ser JSON válido:

Terminal

curl -X POST https://panel.example.com/api/v1/apps/APP_ID/deployments \
  -H "Authorization: Bearer $SH0_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Para criar uma app a partir do seu próprio código, o caminho mais curto é a CLI: sh0 push envia o diretório do projeto como arquivo e o implanta, com ou sem Dockerfile.

Formato de Resposta

Todas as respostas da API sh0 seguem um formato consistente:

Respostas de sucesso:

Success Format

{
  "data": { ... }
}

Respostas de lista com paginação:

List Format

{
  "data": [ ... ],
  "total": 42,
  "page": 1,
  "per_page": 20,
  "pages": 3
}

Respostas de erro:

Error Format

{
  "error": {
    "code": "NOT_FOUND",
    "message": "App with id 'app_xyz' not found"
  }
}

Paginação

Endpoints de lista suportam paginação com dois parâmetros de consulta:

Parâmetro	Padrão	Descrição
`page`	1	Número da página (indexado a partir de 1)
`per_page`	20	Itens por página (máx 100)

Terminal

# Get page 2, 50 items per page
curl "https://panel.example.com/api/v1/apps/APP_ID/deployments?page=2&per_page=50" \
  -H "Authorization: Bearer $SH0_TOKEN"

Tratamento de Erros

A API usa códigos de status HTTP padrão. Aqui estão os mais comuns:

Status	Significado
200	Sucesso
201	Recurso criado
400	Requisição inválida (parâmetros inválidos)
401	Não autorizado (token ausente ou inválido)
403	Proibido (permissões insuficientes)
404	Recurso não encontrado
409	Conflito (nome duplicado, etc.)
422	Erro de validação
429	Limite de taxa excedido
500	Erro interno do servidor

Tip

Sempre verifique o campo error.code para tratamento programático de erros em vez de analisar a string de mensagem, que pode mudar entre versões.

Próximos Passos

Agora que você sabe autenticar e fazer chamadas básicas à API, explore as capacidades completas da API sh0:

Referência Completa da API -- Explorador interativo com todos os 180+ endpoints
Deploy via Git -- Configure fluxos de push-to-deploy
Escalonamento -- Escalar apps via API
Monitoramento -- Recuperar métricas e dados de saúde

Explorador da API sh0 mostrando categorias de endpoints disponíveis

Autenticação da API

Referência completa