Endpoints para gerenciar as instâncias VPS da sua conta: listar, provisionar, controlar energia,
consultar status e métricas, trocar a senha, gerenciar
chaves SSH e resetar. Todas as rotas exigem
autenticação e operam apenas sobre
as VPS que pertencem ao cliente autenticado.
Endpoints
GET
/api/vps
Listar VPS
Lista todas as VPS do cliente autenticado, em formato resumido.
{
"data": [
{
"id": "9f1c8a2e-3b4d-4c5e-9a1b-2c3d4e5f6a7b",
"hostname": "vps-web-01.cliente.com.br",
"ipv4": "203.0.113.10",
"ipv6": "2001:db8:abcd::10",
"power_state": "running",
"is_online": true,
"os": "Ubuntu 22.04 LTS",
"datacenter": {
"id": "4a2b1c3d-...",
"name": "São Paulo - SP1",
"location": "São Paulo, BR"
},
"service": {
"id": "7c8d9e0f-...",
"name": "VPS Cloud 4GB",
"status": "active"
}
}
]
}
POST
/api/vps/provision
Provisionar VPS
Provisiona uma nova VPS. O pagamento é automático: a plataforma tenta usar créditos primeiro e, se
insuficiente, cobra no cartão padrão. Responde 201 em caso de sucesso. Os IDs vêm de
Produtos (product_id) e
Datacenters
(datacenter_id, os_template_id).
Corpo (JSON)
| Campo | Tipo | Descrição |
|---|
product_id obrigatório | uuid | ID do produto VPS (ativo e do tipo VPS). |
datacenter_id obrigatório | uuid | ID do datacenter (deve ter IPs disponíveis). |
os_template_id obrigatório | uuid | ID do template de sistema operacional. |
root_password obrigatório | string (8–128) | Senha root da VPS. |
hostname | string (≤253) | Hostname desejado. Gerado automaticamente se omitido. |
ssh_public_key | string | Chave pública SSH a injetar na VPS. |
addons | object | Mapa { resource_id: quantidade }. Addons obrigatórios são incluídos automaticamente. |
O status vem na resposta — você não envia esse campo
No corpo 201, data.status reflete o resultado do pagamento:
provisioning = pagamento confirmado e provisionamento já iniciado;
pending_payment = cobrança ainda não confirmada pelo gateway (o provisionamento dispara
automaticamente quando o pagamento confirmar). Já os erros de regra de negócio (produto inativo,
datacenter sem IP, cartão expirado) nem chegam a criar a VPS — retornam 422.
{
"success": true,
"data": {
"service_id": "7c8d9e0f-...",
"vps_id": "9f1c8a2e-...",
"status": "provisioning",
"hostname": "vps-web-01.cliente.com.br",
"ssh_port": 22,
"product": {
"id": "1a2b3c4d-...",
"name": "VPS Cloud 4GB"
},
"invoice": {
"invoice_number": "INV-2026-000123",
"amount": 104.9,
"status": "paid"
},
"payment": {
"method": "card",
"credits_used": 0,
"card_last_digits": "4242"
}
}
}
GET
/api/vps/{id}
Detalhar VPS
Retorna os detalhes completos de uma VPS: acesso, serviço, tráfego, monitoramento, backup e timestamps.
Parâmetros de rota
| Campo | Tipo | Descrição |
|---|
id obrigatório | uuid | ID da VPS (deve pertencer à sua conta). |
A senha root nunca é exposta — apenas access.has_root_password. Retorna 404 se a VPS não existir ou não for sua.
{
"data": {
"id": "9f1c8a2e-...",
"hostname": "vps-web-01.cliente.com.br",
"ipv4": "203.0.113.10",
"power_state": "running",
"is_online": true,
"os": "Ubuntu 22.04 LTS",
"service": {
"name": "VPS Cloud 4GB",
"status": "active",
"price": 89.9,
"billing_cycle": "monthly",
"next_billing_date": "2026-07-28T00:00:00+00:00"
},
"access": {
"has_root_password": true,
"ipv4": "203.0.113.10",
"ssh_port": 22
},
"traffic": {
"used": 5368709120,
"limit": 1099511627776,
"percentage": 0.49,
"formatted": "5 GB / 1 TB"
},
"backup": {
"enabled": true,
"schedule": "daily",
"last_backup_at": "2026-06-28T03:00:00+00:00"
}
}
}
POST
/api/vps/{id}/start
Ligar VPS
Inicia (liga) a VPS. Retorna 409 se ela já estiver ligada.
Parâmetros de rota
| Campo | Tipo | Descrição |
|---|
id obrigatório | uuid | ID da VPS. |
{
"message": "VPS start initiated",
"data": {
"id": "9f1c8a2e-...",
"hostname": "vps-web-01.cliente.com.br",
"power_state": "running"
}
}
POST
/api/vps/{id}/stop
Desligar VPS
Desliga a VPS de forma graciosa (shutdown). Retorna 409 se já estiver desligada.
Parâmetros de rota
| Campo | Tipo | Descrição |
|---|
id obrigatório | uuid | ID da VPS. |
{
"message": "VPS stop initiated",
"data": {
"id": "9f1c8a2e-...",
"hostname": "vps-web-01.cliente.com.br",
"power_state": "stopped",
"is_online": false
}
}
POST
/api/vps/{id}/restart
Reiniciar VPS
Reinicia a VPS. Retorna 409 se ela estiver desligada (use ligar).
Parâmetros de rota
| Campo | Tipo | Descrição |
|---|
id obrigatório | uuid | ID da VPS. |
{
"message": "VPS restart initiated",
"data": {
"id": "9f1c8a2e-...",
"hostname": "vps-web-01.cliente.com.br",
"power_state": "running"
}
}
POST
/api/vps/{id}/force-stop
Forçar desligamento
Força o desligamento imediato (hard shutdown). Retorna 409 se já estiver desligada.
Parâmetros de rota
| Campo | Tipo | Descrição |
|---|
id obrigatório | uuid | ID da VPS. |
{
"message": "VPS force stop initiated",
"data": {
"id": "9f1c8a2e-...",
"hostname": "vps-web-01.cliente.com.br",
"power_state": "stopped",
"is_online": false
}
}
GET
/api/vps/{id}/status
Status da VPS
Estado de energia atual, uptime e timestamps. uptime é null quando a VPS não está rodando.
Parâmetros de rota
| Campo | Tipo | Descrição |
|---|
id obrigatório | uuid | ID da VPS. |
{
"data": {
"id": "9f1c8a2e-...",
"power_state": "running",
"is_online": true,
"uptime": "2d 4h 15m",
"timestamps": {
"last_started_at": "2026-06-26T09:50:00+00:00",
"last_ping_at": "2026-06-28T14:00:00+00:00"
}
}
}
GET
/api/vps/{id}/metrics
Métricas da VPS
Tráfego, rede, monitoramento, backup, uso de disco e séries temporais (RRD do Proxmox).
Parâmetros de rota
| Campo | Tipo | Descrição |
|---|
id obrigatório | uuid | ID da VPS. |
Query string
| Campo | Tipo | Descrição |
|---|
timeframe | hour|day|week|month|year | Janela do gráfico. Padrão: hour. |
Unidades dos pontos: time em segundos Unix; cpu fração 0..1; memória e disco
em bytes; netin/netout/diskread/diskwrite em bytes por segundo. Sem provisionamento ou nó
inacessível, charts.points vem [] com HTTP 200.
{
"data": {
"id": "9f1c8a2e-...",
"traffic": {
"used": 5368709120,
"limit": 1099511627776,
"percentage": 0.49,
"exceeded": false
},
"disk": {
"used": 12884901888,
"total": 85899345920,
"percentage": 15,
"source": "storage-allocation"
},
"charts": {
"timeframe": "hour",
"points": [
{
"time": 1782658800,
"cpu": 0.0423,
"mem": 1610612736,
"maxmem": 4294967296,
"netin": 10485,
"netout": 8192
}
]
}
}
}
POST
/api/vps/{id}/password
Trocar senha
Troca a senha do usuário no SO da VPS (via guest agent, na hora). A VPS precisa estar ligada
e com o guest agent disponível. Não altera o cloud-init.
Parâmetros de rota
| Campo | Tipo | Descrição |
|---|
id obrigatório | uuid | ID da VPS. |
Corpo (JSON)
| Campo | Tipo | Descrição |
|---|
username | root|administrator | Usuário alvo. Padrão: root. |
password obrigatório | string (8–72) | Nova senha. |
password_confirmation obrigatório | string | Confirmação da senha (igual a password). |
VPS desligada → 409. Guest agent indisponível → 409. Sucesso → 200.
GET
/api/vps/{id}/os-templates
Templates de SO da VPS
Lista os templates de SO disponíveis no datacenter desta VPS — use um id daqui no reset (troca de SO).
Parâmetros de rota
| Campo | Tipo | Descrição |
|---|
id obrigatório | uuid | ID da VPS. |
{
"data": [
{
"id": "5e1b0c9a-...",
"display_name": "Ubuntu 22.04 LTS",
"os_family": "linux",
"os_type": "ubuntu",
"additional_price": 0,
"min_requirements": {
"cpu_cores": 1,
"ram_gb": 1,
"storage_gb": 10
}
}
]
}
POST
/api/vps/{id}/reset
Resetar (reinstalar)
Reseta a VPS para uma instalação limpa do SO (enfileirado). Destrutivo: apaga todos os
dados da VPS. Pode trocar o SO por outro template do mesmo datacenter
(ver templates da VPS). Responde 202.
Parâmetros de rota
| Campo | Tipo | Descrição |
|---|
id obrigatório | uuid | ID da VPS. |
Corpo (JSON)
| Campo | Tipo | Descrição |
|---|
os_template_id obrigatório | uuid | Template de SO (deve ser do datacenter da VPS). |
confirm obrigatório | boolean | Deve ser true — confirma a operação destrutiva. |
keep_password | boolean | Manter a senha atual. Padrão: true. |
new_password | string (8–72) | Nova senha (obrigatória se keep_password=false). |
keep_ssh_keys | boolean | Manter as chaves SSH atuais. Padrão: true. |
ssh_key_ids | uuid[] | Chaves a aplicar quando keep_ssh_keys=false. |
Pré-condições: VPS provisionada, com IP, serviço ativo e não em reset — senão 409. Template
de outro datacenter → 422.