Documentação da API — VPS por Hora (KVM)

Crie, consulte e destrua máquinas virtuais sob demanda com /dev/kvm (Nested Virtualization) habilitado e cobrança proporcional por tempo de uso.

Autenticação e Base URL

Todas as chamadas usam a Base URL https://yousecure.io e autenticam via cabeçalho Authorization: Bearer SEU_TOKEN (ou X-API-Key: SEU_TOKEN).

Plan ID Configuração Base Valor / Hora (Disco Base) Valor / Hora (150 GB: 40 GB OS + 110 GB ZFS)
starter 2 vCPUs • 4 GB RAM • 30 GB SSD R$ 0,10 / h R$ 0,21 / h
basic 4 vCPUs • 8 GB RAM • 40 GB SSD R$ 0,18 / h R$ 0,28 / h
performance 6 vCPUs • 12 GB RAM • 60 GB SSD R$ 0,29 / h R$ 0,38 / h
ultra 8 vCPUs • 16 GB RAM • 80 GB SSD R$ 0,42 / h R$ 0,49 / h

GET /api/v1/nested-kvm/balance

Consulta seu saldo atual de créditos em Reais (BRL), limite de VMs simultâneas e tabela de planos.

curl -s https://yousecure.io/api/v1/nested-kvm/balance \
  -H "Authorization: Bearer SEU_TOKEN"
{
  "account_id": "kvm_...",
  "balance_brl": 2.0,
  "max_vms": 4,
  "default_os": "debian-13",
  "images": {
    "debian-13": { "id": "debian-13", "name": "Debian 13 (Trixie)", "default": true },
    "ubuntu-24.04": { "id": "ubuntu-24.04", "name": "Ubuntu 24.04 LTS (Noble)", "default": false }
  },
  "plans": { ... }
}

POST /api/v1/nested-kvm/vms

Cria e inicia uma nova VM em ~15 segundos. Todos os recursos da máquina (sistema operacional, tamanho do disco, divisão de partição para ZFS, segundo disco dedicado e script Cloud-Init) são escolhidos diretamente no JSON da requisição:

Campo JSON Tipo Padrão Descrição
vm_name string (obrigatório) — Nome único da sua VM (2 a 48 caracteres: letras, números, -, _ ou .).
plan string performance Plano de vCPU/RAM: starter, basic, performance ou ultra.
os string debian-13 Sistema operacional: debian-13 (Debian 13 Trixie) ou ubuntu-24.04 (Ubuntu 24.04 LTS).
disk_gb integer Disco base do plano (30–80 GB) Tamanho total do disco principal /dev/vda (de 20 a 250 GB). Ex: 150 para 150 GB. Cobrança proporcional quando acima do disco base do plano.
os_disk_gb integer 40 (se disk_gb >= 80) ou 0 Reserva esse tamanho (ex: 40 GB) para o sistema em /dev/vda1 e cria automaticamente uma partição vazia /dev/vda2 (tipo GPT ZFS) com o espaço restante (ex: 110 GB livres em um disco de 150 GB). Envie 0 para o sistema ocupar 100% do disco.
zfs_disk_gb integer 0 Opcional: anexa um 2º disco VirtIO separado e 100% vazio em /dev/vdb (de 5 a 200 GB).
user_data string — Opcional: Cloud-Init customizado (deve iniciar com #cloud-config ou #!/), aceito em texto puro ou codificado em Base64 (máx. 32 KB).
ssh_pubkey string Chave da conta Chave pública SSH (ssh-ed25519, ssh-rsa ou ecdsa) injetada no usuário root.
curl -s -X POST https://yousecure.io/api/v1/nested-kvm/vms \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vm_name": "worker-01",
    "plan": "basic",
    "os": "debian-13",
    "disk_gb": 150,
    "os_disk_gb": 40,
    "user_data": "#cloud-config\nruncmd:\n  - echo pronto > /root/ready.txt",
    "ssh_pubkey": "ssh-ed25519 AAAA... seu-usuario@host"
  }'
{
  "vm_name": "worker-01",
  "plan": "basic",
  "os": "debian-13",
  "vcpus": 4,
  "ram_gb": 8,
  "disk_gb": 150,
  "os_disk_gb": 40,
  "zfs_partition_gb": 110,
  "extra_disk_gb": 0,
  "hourly_rate_brl": 0.28,
  "private_ip": "192.168.122.45",
  "ssh_host": "178.83.141.102",
  "ssh_port": 22045,
  "ssh_command": "ssh -p 22045 [email protected]",
  "status": "running"
}

Dica: após o retorno, aguarde ~10 segundos para o Cloud-Init aplicar sua chave SSH e conecte com o comando retornado em ssh_command. Dentro da VM, ls -l /dev/kvm já estará disponível.

GET /api/v1/nested-kvm/vms

Lista todas as suas VMs em execução, seus IPs privados, portas SSH públicas e o valor acumulado já debitado.

curl -s https://yousecure.io/api/v1/nested-kvm/vms \
  -H "Authorization: Bearer SEU_TOKEN"

GET /api/v1/nested-kvm/vms/<vm_name>

Consulta o estado em tempo real de uma VM específica no hypervisor e atualiza o IP/porta caso tenha acabado de subir.

curl -s https://yousecure.io/api/v1/nested-kvm/vms/worker-01 \
  -H "Authorization: Bearer SEU_TOKEN"

POST /api/v1/nested-kvm/vms/<vm_name>/stop

Desliga a VM preservando todo o disco (inclusive dados, ZFS e boxes). Enquanto desligada, zera a cobrança de vCPU/RAM e passa a cobrar apenas pelo espaço real ocupado em disco (thin-provisioned em qcow2, R$ 0,001/GB usado/hora — ex.: 10 GB usados custam apenas R$ 0,01/h).

curl -s -X POST https://yousecure.io/api/v1/nested-kvm/vms/worker-01/stop \
  -H "Authorization: Bearer SEU_TOKEN"
{
  "vm_name": "worker-01",
  "status": "stopped",
  "used_disk_gb": 10.45,
  "stopped_hourly_rate_brl": 0.0105,
  "charged_brl": 0.0412,
  "balance_brl": 1.9588
}

POST /api/v1/nested-kvm/vms/<vm_name>/start

Religa uma VM que estava em stopped mantendo todo o disco intacto, reabrindo a porta SSH e retomando a tarifa normal do plano.

curl -s -X POST https://yousecure.io/api/v1/nested-kvm/vms/worker-01/start \
  -H "Authorization: Bearer SEU_TOKEN"
{
  "vm_name": "worker-01",
  "status": "running",
  "hourly_rate_brl": 0.49,
  "private_ip": "192.168.122.230",
  "ssh_host": "178.83.141.102",
  "ssh_port": 22230,
  "ssh_command": "ssh -p 22230 [email protected]"
}

DELETE /api/v1/nested-kvm/vms/<vm_name>

Destrói a VM imediatamente, remove o disco efêmero, fecha o redirecionamento de porta e encerra a cobrança por hora (respeitando o piso mínimo de 5 minutos por criação).

curl -s -X DELETE https://yousecure.io/api/v1/nested-kvm/vms/worker-01 \
  -H "Authorization: Bearer SEU_TOKEN"
{
  "vm_name": "worker-01",
  "status": "destroyed",
  "charged_brl": 0.0292,
  "balance_brl": 1.9708
}
Estamos online