Documentação da API

Referência completa da API Hostly Cloud. Use esses endpoints para gerenciar apps, bancos de dados, arquivos e métricas programaticamente.

Base URL: https://api.hostlycloud.online/v1
Todas as requisições devem usar HTTPS.

Visão Geral

A API Hostly Cloud é RESTful e retorna respostas no formato JSON. Todos os endpoints (exceto autenticação do painel) exigem uma API Key válida no header x-api-key.

A API é dividida em 6 grupos principais:

Apps — Gerenciamento de aplicações (start, stop, restart, delete, logs)
Databases — Criação e gerenciamento de PostgreSQL e MongoDB
Upload — Criação de novas aplicações via ZIP
Edit — Edição de nome, arquivo principal e RAM
Files — File manager para manipular arquivos dentro do container
Metrics — Métricas de uso, CPU, memória e disco

Autenticação

Todas as rotas da API exigem autenticação via header x-api-key. Sua API Key pode ser gerada e consultada na página de Perfil do painel.

Nunca exponha sua API Key em repositórios públicos ou no frontend de produção. Ela concede acesso total aos seus recursos na HostlyCloud.

O formato da API Key segue o padrão:

Formato

hl_<prefixo>_<secreto>

Exemplo de requisição autenticada:

cURL

curl -X GET "https://api.hostlycloud.online/v1/status" \
  -H "x-api-key: hl_a1b2c3d4_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Códigos de Status

Código	Significado
200	Sucesso na requisição
201	Recurso criado com sucesso
400	Requisição inválida (parâmetros faltando ou incorretos)
401	Não autorizado (API Key ausente, inválida ou expirada)
403	RAM insuficiente no plano do usuário
404	Recurso não encontrado ou acesso negado
409	Conflito (nome em uso, app já online/offline)
413	Arquivo muito grande (limite de 2MB para leitura, 500MB para upload)
500	Erro interno do servidor
503	Limite da host atingido (capacidade de RAM esgotada)

Apps

Endpoints para gerenciar aplicações hospedadas. Apps são identificados pelo campo name (nome único do usuário).

GET /status

Retorna todos os apps do usuário autenticado. Bancos de dados são excluídos desta listagem.

Response 200

{
  "success": true,
  "count": 2,
  "userId": "123456789",
  "apps": [
    {
      "id": "1234567890-meuapp",
      "name": "meuapp",
      "language": "nodejs",
      "status": "online",
      "memory": "512MB",
      "port": 15432,
      "domain": "meuapp.hostlycloud.online",
      "runtimeImage": "node:20-alpine",
      "startFile": "index.js",
      "createdAt": "2025-01-15T10:30:00.000Z"
    }
  ]
}

GET /all

Retorna apps e databases do usuário em categorias separadas.

Response 200

{
  "success": true,
  "userId": "123456789",
  "total": 3,
  "apps": { "count": 2, "items": [...] },
  "databases": {
    "count": 1,
    "items": [
      {
        "id": "...",
        "name": "meubanco",
        "type": "database",
        "status": "online",
        "memory": "512MB",
        "dbType": "postgres",
        "port": 23456,
        "dbUser": "hostly_admin",
        "dbName": "hostly_db",
        "dbUri": "postgresql://hostly_admin:senha@db.hostlycloud.online:23456/hostly_db"
      }
    ]
  }
}

POST /start

Inicia uma aplicação que está offline.

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do app a ser iniciado

Body

{ "name": "meuapp" }

POST /stop

Para uma aplicação que está online.

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do app a ser parado

Body

{ "name": "meuapp" }

POST /restart

Reinicia uma aplicação (stop + start).

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do app a ser reiniciado

Body

{ "name": "meuapp" }

DELETE /delete

Deleta permanentemente um app, incluindo arquivos, container, proxy e logs. Requer confirmação em duas etapas.

Etapa 1: Envie apenas o nome para receber o aviso de confirmação.

Body (confirmação)

{ "name": "meuapp" }

Etapa 2: Envie confirm: true para executar a deleção.

Body (execução)

{ "name": "meuapp", "confirm": true }

GET /logs/:name

Retorna os logs de um app. Use o query param lines para limitar (padrão: 50).

Exemplo

GET /v1/logs/meuapp?lines=100

Response 200

{
  "success": true,
  "app": { "id": "...", "name": "meuapp" },
  "logs": ["log line 1", "log line 2", "..."]
}

Bancos de Dados

Endpoints para criação e gerenciamento de bancos de dados PostgreSQL e MongoDB.

POST /databases/create

Cria um novo banco de dados hospedado.

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome único (a-z, 0-9, -, _). Máx 40 chars
`dbType`	string	Sim	`postgres` ou `mongo`
`password`	string	Sim	8-20 caracteres, apenas letras e números
`memory`	string	Sim	Mínimo 256MB. Ex: `512MB`, `1GB`

Body

{
  "name": "meubanco",
  "dbType": "postgres",
  "password": "minhasenha123",
  "memory": "512MB"
}

Response 201

{
  "success": true,
  "message": "Banco de dados hospedado com sucesso.",
  "database": {
    "id": "1234567890-db-meubanco",
    "name": "meubanco",
    "dbType": "postgres",
    "memory": "512MB",
    "status": "online",
    "port": 23456,
    "dbUser": "hostly_admin",
    "dbName": "hostly_db",
    "dbUri": "postgresql://hostly_admin:minhasenha123@db.hostlycloud.online:23456/hostly_db"
  }
}

GET /databases

Lista todos os bancos de dados do usuário.

POST /databases/start

Inicia um database que está offline.

Body

{ "name": "meubanco" }

POST /databases/stop

Para um database que está online.

Body

{ "name": "meubanco" }

POST /databases/restart

Reinicia um database.

Body

{ "name": "meubanco" }

DELETE /databases/delete

Deleta permanentemente um database, incluindo todos os dados. Requer confirmação em duas etapas.

Body (confirmação)

{ "name": "meubanco" }

Body (execução)

{ "name": "meubanco", "confirm": true }

GET /databases/logs/:name

Retorna os logs de um database.

Exemplo

GET /v1/databases/logs/meubanco?lines=100

Upload / Criar Aplicação

POST /upload

Cria uma nova aplicação a partir de um arquivo ZIP. Suporta apps normais (bot) e websites (estático ou com backend).

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome único (a-z, 0-9, -, _). Máx 40 chars
`language`	string	Sim	`nodejs`, `python`, `go`, `rust`, `website`
`memory`	string	Sim	Ex: `256MB`, `1GB`
`zipUrl` ou `zipBase64`	string	Sim	URL direta do ZIP ou conteúdo em base64
`startFile`	string	Condicional	Arquivo principal (exceto website estático)
`appType`	string	Se website	`web` (estático) ou `api` (com backend)
`runtimeLanguage`	string	Se api	Linguagem do backend: `nodejs`, `python`, `go`, `rust`

Exemplo: Bot Node.js

Body

{
  "name": "meubot",
  "language": "nodejs",
  "startFile": "index.js",
  "memory": "512MB",
  "zipUrl": "https://exemplo.com/codigo.zip"
}

Exemplo: Website Estático

Body

{
  "name": "meusite",
  "language": "website",
  "appType": "web",
  "memory": "256MB",
  "zipBase64": "UEsDBBQACAAI..."
}

Exemplo: Website com Backend

Body

{
  "name": "minhaapi",
  "language": "website",
  "appType": "api",
  "runtimeLanguage": "nodejs",
  "startFile": "server.js",
  "memory": "512MB",
  "zipUrl": "https://exemplo.com/api.zip"
}

Edição

POST /edit/name

Altera o nome de uma aplicação ou database.

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome atual do recurso
`newName`	string	Sim	Novo nome (a-z, 0-9, -, _). Máx 40 chars

Body

{
  "name": "meuapp",
  "newName": "meunovoapp"
}

POST /edit/file

Altera o arquivo principal de inicialização de um app.

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do app
`startFile`	string	Sim	Novo arquivo principal (ex: `server.js`)

Body

{
  "name": "meuapp",
  "startFile": "server.js"
}

POST /edit/ram

Altera a RAM de um app ou database. Se o recurso estiver online, ele será parado e reiniciado automaticamente.

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do recurso
`memory`	string	Sim	Novo valor (ex: `512MB`, `1GB`)

Body

{
  "name": "meuapp",
  "memory": "1GB"
}

Databases precisam de no mínimo 256MB. A mudança não pode ultrapassar o limite do seu plano nem a capacidade disponível da host.

Gerenciamento de Arquivos

Manipule arquivos e diretórios dentro do container da aplicação. Não funciona para databases.

GET /files/:name/list?path=

Lista o conteúdo de um diretório dentro do app.

Exemplo

GET /v1/files/meuapp/list?path=src/

GET /files/:name/read?path=

Lê o conteúdo de um arquivo como texto. Limite de 2MB.

Exemplo

GET /v1/files/meuapp/read?path=index.js

POST /files/:name/write

Cria ou sobrescreve um arquivo.

Parâmetro	Tipo	Obrigatório	Descrição
`path`	string	Sim	Caminho relativo do arquivo
`content`	string	Sim	Conteúdo do arquivo
`encoding`	string	Não	Padrão: `utf8`

Body

{
  "path": "config.json",
  "content": "{\"port\": 3000}",
  "encoding": "utf8"
}

DELETE /files/:name/delete

Deleta um arquivo ou pasta (recursivamente).

Body

{ "path": "temp/old.js" }

POST /files/:name/move

Renomeia ou move um arquivo/pasta.

Parâmetro	Tipo	Obrigatório	Descrição
`from`	string	Sim	Caminho de origem
`to`	string	Sim	Caminho de destino

Body

{
  "from": "a.js",
  "to": "b.js"
}

POST /files/:name/mkdir

Cria um novo diretório (cria pastas pai automaticamente).

Body

{ "path": "src/utils" }

GET /files/:name/download?path=

Faz o download raw de um arquivo com Content-Disposition: attachment.

Exemplo

GET /v1/files/meuapp/download?path=package.json

POST /files/:name/upload

Faz upload de um arquivo codificado em Base64.

Parâmetro	Tipo	Obrigatório	Descrição
`path`	string	Sim	Caminho de destino
`contentBase64`	string	Sim	Conteúdo do arquivo em base64

Body

{
  "path": "uploads/img.png",
  "contentBase64": "iVBORw0KGgo..."
}

GET /files/:name/info

Retorna estatísticas do app: tamanho total, quantidade de arquivos e pastas.

Response 200

{
  "success": true,
  "app": "meuapp",
  "appId": "1234567890-meuapp",
  "totalSizeBytes": 5242880,
  "totalSizeMB": "5.00",
  "fileCount": 12,
  "dirCount": 3
}

Métricas

GET /metrics

Retorna métricas de todos os recursos do usuário + informações da host.

Response 200 (resumo)

{
  "success": true,
  "user": {
    "userId": "123456789",
    "plan": "Pro",
    "maxRam": "2GB",
    "usedRam": "768MB",
    "availableRam": "1.25GB"
  },
  "host": {
    "totalRamMB": 8192,
    "usedRamMB": 4096,
    "availableRamMB": 4096,
    "cpuLoad1m": "0.45",
    "totalContainers": 15
  },
  "count": 3,
  "online": 2,
  "offline": 1,
  "items": [
    {
      "id": "...",
      "name": "meuapp",
      "type": "app",
      "status": "online",
      "memory": {
        "configured": "512MB",
        "configuredMB": 512,
        "usage": "45.2MiB / 512MiB",
        "percentage": "8.83%"
      },
      "cpu": "2.34%",
      "uptime": { "ms": 3600000, "formatted": "1h" },
      "diskUsage": { "mb": 45.23, "formatted": "45.2 MB" },
      "network": "1.2MB / 500KB",
      "processes": "12"
    }
  ]
}

GET /metrics/:name

Retorna métricas detalhadas de um app ou database específico.

Exemplo

GET /v1/metrics/meuapp

Response 200

{
  "success": true,
  "id": "...",
  "name": "meuapp",
  "type": "app",
  "status": "online",
  "memory": {
    "configured": "512MB",
    "configuredMB": 512,
    "limitFormatted": "512MB",
    "usage": "45.2MiB / 512MiB",
    "percentage": "8.83%"
  },
  "cpu": { "limit": "1 vCPU", "usage": "2.34%" },
  "uptime": { "ms": 3600000, "formatted": "1h" },
  "pid": 12345,
  "diskUsage": { "mb": 45.23, "formatted": "45.2 MB" },
  "userPlan": {
    "plan": "Pro",
    "maxRam": "2GB",
    "totalUsedRam": "768MB",
    "availableRam": "1.25GB"
  }
}

GET /metrics/host

Retorna métricas gerais da máquina host. Visível para todos os usuários autenticados.

Response 200

{
  "success": true,
  "host": {
    "hostname": "hostly-server-01",
    "platform": "linux",
    "arch": "x64",
    "cpuCores": 8,
    "cpuLoad1m": 0.45,
    "systemUptimeHours": 720.5
  },
  "memory": {
    "physicalTotalGB": 16,
    "usableTotalGB": 14.5,
    "usedGB": 4,
    "availableGB": 10.5
  },
  "docker": { "activeContainers": 15 },
  "apps": { "total": 25, "online": 18, "offline": 7 }
}

Exemplos Completos

Criar um bot Node.js

cURL

curl -X POST "https://api.hostlycloud.online/v1/upload" \
  -H "x-api-key: hl_seu_prefixo_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "meubot",
    "language": "nodejs",
    "startFile": "index.js",
    "memory": "512MB",
    "zipUrl": "https://github.com/user/repo/archive/main.zip"
  }'

Iniciar um app

cURL

curl -X POST "https://api.hostlycloud.online/v1/start" \
  -H "x-api-key: hl_seu_prefixo_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{"name": "meubot"}'

Ver logs

cURL

curl "https://api.hostlycloud.online/v1/logs/meubot?lines=100" \
  -H "x-api-key: hl_seu_prefixo_sua_chave_aqui"

Criar database PostgreSQL

cURL

curl -X POST "https://api.hostlycloud.online/v1/databases/create" \
  -H "x-api-key: hl_seu_prefixo_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "meubanco",
    "dbType": "postgres",
    "password": "senhaSegura123",
    "memory": "512MB"
  }'

Editar arquivo via API

cURL

curl -X POST "https://api.hostlycloud.online/v1/files/meubot/write" \
  -H "x-api-key: hl_seu_prefixo_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "path": ".env",
    "content": "TOKEN=seu_token_aqui\nPREFIX=!"
  }'

Ver métricas

cURL

curl "https://api.hostlycloud.online/v1/metrics" \
  -H "x-api-key: hl_seu_prefixo_sua_chave_aqui"