Servidores da conta

GET /cloud/servers

Escopo do token: servers:read. Recurso: Servidores.

Filtros: status (um ou mais, separados por vírgula), site_id, plan_id, hostname_prefix, tag, external_id e end_customer_ref, aplicados no banco. Paginação por cursor opcional (limit, cursor).

Exemplo de requisição

Os exemplos leem o token da variável de ambiente HALVER_API_TOKEN (um token sc_live_… criado em Desenvolvedores › Tokens de API). Nunca escreva o token no código.

curl "https://dash.halver.com.br/api/v1/cloud/servers?limit=50" \
  -H "Authorization: Bearer $HALVER_API_TOKEN"

package main

import (
  "fmt"
  "io"
  "net/http"
  "os"
  "time"
)

func main() {
  req, err := http.NewRequest(http.MethodGet, "https://dash.halver.com.br/api/v1/cloud/servers?limit=50", nil)
  if err != nil {
    panic(err)
  }
  req.Header.Set("Authorization", "Bearer "+os.Getenv("HALVER_API_TOKEN"))
  client := &http.Client{Timeout: 30 * time.Second}
  resp, err := client.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()
  out, err := io.ReadAll(resp.Body)
  if err != nil {
    panic(err)
  }
  fmt.Println(resp.Status)
  fmt.Println(string(out))
}

import os

import requests

resp = requests.get(
    "https://dash.halver.com.br/api/v1/cloud/servers?limit=50",
    headers={
        "Authorization": f"Bearer {os.environ['HALVER_API_TOKEN']}",
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Parâmetros

Parâmetros de consulta

limit integer
Tamanho da página, de 1 a 100. Com limit ou cursor a resposta é uma página em ordem de criação (mais antigo primeiro, depois o id) e next_cursor aponta a próxima; sem os dois vem a lista inteira, na ordem de sempre, com next_cursor nulo (compatibilidade). Com cursor e sem limit, páginas de 50. De 1 a 100. Veja Paginação.
cursor string
O next_cursor da página anterior desta mesma lista (opaco; 400 invalid_cursor se não for). Até 200 caracteres. Veja Paginação.
external_id string
Id do pedido no sistema do revendedor, o external_id do servidor. Formato: ^[A-Za-z0-9._:-]{1,128}$.
end_customer_ref string
Id do cliente final no sistema do revendedor, o end_customer_ref do servidor. Formato: ^[A-Za-z0-9._:-]{1,128}$.
status string
pending_payment, deploying, active, failed, wiping, empty ou deleting; vários separados por vírgula.
site_id string (uuid)
plan_id string (uuid)
hostname_prefix string
Até 63 caracteres.
tag string
Até 64 caracteres.

Respostas

200

Servidores.

Campos da resposta

items array de object obrigatório
- cancel_at string (date) obrigatório pode ser nulo
  Último dia da assinatura cancelada (fim do período pago); depois dele a máquina volta ao estoque.
- contract_id string (uuid) obrigatório pode ser nulo
- created_at string (date-time) obrigatório
- description string
  Descrição livre do cliente (até 500 caracteres).
- disk_layout string obrigatório
  Legado (veja storage) - raid1 quando a última instalação é um RAID 1, senão single. Um de: single, raid1.
- end_customer_ref string pode ser nulo
  Id do cliente final no sistema do revendedor: agrupa servidores, não é único. Id opaco, sem dado pessoal (nem nome nem CPF), com a mesma regra do external_id. Nulo quando não informado.
- external_id string pode ser nulo
  Id do pedido no sistema do revendedor: único na conta entre os servidores não removidos. Id opaco, sem dado pessoal (nem nome nem CPF): de 1 a 128 caracteres entre letras sem acento, números e . _ : -. Nulo quando não informado.
- first_invoice_id string (uuid) obrigatório pode ser nulo
  Fatura cobrada na compra.
- hostname string obrigatório
- id string (uuid) obrigatório
- ipv4 string obrigatório
- ipv4_gateway string obrigatório
- ipv4_prefix integer obrigatório
- monthly_cents integer (int64) obrigatório
  O que o servidor custa por mês: a recorrência do contrato dele (com reajustes), não o preço atual do plano, que vale só para servidores novos.
- operation string obrigatório
  Um de: deploy, reinstall, wipe, delete, "" (vazio).
- operation_id string (uuid) pode ser nulo
  A última operação do servidor (deploy, reinstall, wipe ou delete); acompanhe por GET /cloud/operations/{id}.
- os object obrigatório
  - code string obrigatório
  - family string obrigatório
  - id string (uuid) obrigatório
  - install_method string obrigatório
    image grava uma imagem de disco; installer inicia o instalador oficial do sistema (Proxmox VE); none não instala nada (o cliente instala o próprio sistema pela IPMI). Um de: image, installer, none.
  - login_user string obrigatório
    Usuário de acesso ao sistema instalado.
  - name string obrigatório
  - password_required boolean obrigatório
    O sistema é usado com senha (painel web do Proxmox VE).
  - raid1 boolean obrigatório
    O sistema instala num espelho (RAID 1) de dois discos iguais.
  - storage object obrigatório
    O que o cliente escolhe nos discos deste sistema. O instalador do Proxmox VE grava ZFS (padrão, recomendado), ext4 ou XFS; ext4 e XFS vão num disco, o ZFS num disco ou nos níveis de RAID. Um sistema de imagem vai num disco (o sistema de arquivos é o da imagem) ou, quando o motor tem a versão dele para espelho, em RAID 1 de dois discos iguais.
    - default_filesystem string obrigatório
      Um de: zfs, ext4, xfs, "" (vazio).
    - filesystems array de string obrigatório
      Sistemas de arquivos que o instalador grava; vazio nos sistemas de imagem. Um de: zfs, ext4, xfs.
    - levels array de object obrigatório
      - even_disks boolean obrigatório
        O nível usa discos em pares (RAID 10).
      - filesystems array de string obrigatório
        Sistemas de arquivos que oferecem o nível; vazio nos sistemas de imagem. Um de: zfs, ext4, xfs.
      - level string obrigatório
        Um de: single, raid0, raid1, raid10, raidz-1, raidz-2, raidz-3.
      - max_disks integer obrigatório
        0 é sem limite.
      - min_disks integer obrigatório
  - version string obrigatório
- password_login boolean obrigatório
  Cada instalação gera uma senha e a envia por e-mail.
- plan object obrigatório
  - active boolean obrigatório
  - bandwidth_mbps integer obrigatório
    Limite de banda; 0 é a porta inteira.
  - boot_slot string
    Disco pelo qual o servidor inicia (id de disk_slots): o sistema precisa incluí-lo, sozinho ou num pool de discos iguais. As máquinas iniciam em BIOS legado só pelo primeiro disco. Ausente quando qualquer disco inicia o servidor.
  - code string obrigatório
  - cores integer obrigatório
  - cpu string obrigatório
  - cpu_threads integer obrigatório
  - created_at string (date-time) obrigatório
  - disk_slots array de object obrigatório
    Os discos do plano um a um, onde o sistema pode ser instalado.
    - id string obrigatório
      <tipo>-<GB>-<n>, por exemplo ssd-128-2: o segundo SSD de 128 GB do plano.
    - model string obrigatório
    - size_gb integer obrigatório
    - type string obrigatório
      Um de: nvme, ssd, hdd.
  - disks array de object obrigatório
    Discos mínimos que a máquina precisa ter.
    - count integer obrigatório
    - model string
    - size_gb integer obrigatório
    - type string obrigatório
      Um de: nvme, ssd, hdd.
  - id string (uuid) obrigatório
  - memory_gb integer obrigatório
  - monthly_cents integer (int64) obrigatório
  - name string obrigatório
  - port_speed_mbps integer obrigatório
    Velocidade da porta entregue.
  - product_id string (uuid) obrigatório pode ser nulo
  - raid1 boolean obrigatório
    O plano tem dois discos iguais, então o servidor pode espelhá-los (RAID 1).
  - traffic_tb integer obrigatório
    Tráfego mensal em TB; 0 é ilimitado.
- power string obrigatório
  Um de: on, off, unknown.
- site object obrigatório
  - active boolean obrigatório
  - city string obrigatório
  - code string obrigatório
  - country string obrigatório
  - created_at string (date-time) obrigatório
  - id string (uuid) obrigatório
  - name string obrigatório
  - region_id string (uuid) obrigatório
    Região do local; os IPs das máquinas vêm dos blocos dela.
- ssh_keys integer obrigatório
  Quantidade de chaves instaladas no último deploy.
- status string obrigatório
  Um de: pending_payment, deploying, active, failed, wiping, empty, deleting, deleted.
- steps array de object obrigatório
  - finished_at string (date-time) obrigatório pode ser nulo
  - message string obrigatório
  - name string obrigatório
    Um de: prepare, erase, install, configure, reboot, ready, release.
  - started_at string (date-time) obrigatório pode ser nulo
  - status string obrigatório
    Um de: pending, running, done, failed.
- storage object obrigatório
  Onde a última instalação pôs o sistema.
  - disks array de object obrigatório
    - id string obrigatório
      <tipo>-<GB>-<n>, por exemplo ssd-128-2: o segundo SSD de 128 GB do plano.
    - model string obrigatório
    - size_gb integer obrigatório
    - type string obrigatório
      Um de: nvme, ssd, hdd.
  - filesystem string obrigatório
    Vazio nos sistemas de imagem (o sistema de arquivos é o da imagem). Um de: zfs, ext4, xfs, "" (vazio).
  - raid string obrigatório
    Um de: single, raid0, raid1, raid10, raidz-1, raidz-2, raidz-3.
  - summary string obrigatório
- suspended_at string (date-time) obrigatório pode ser nulo
  Desligado por falta de pagamento, com os dados mantidos; volta a ser ligado sozinho quando a fatura é paga. Enquanto isso, power, reinstalação, apagar, cancelar e VPN da IPMI respondem 409 cloud.server_suspended.
- tags array de string
  Tags do cliente, em ordem alfabética e sem repetição.
- terminated_at string (date-time) obrigatório pode ser nulo
  Encerrado na hora pela equipe. O cliente continua vendo a página do servidor (o aviso leva até ela) mesmo depois de removido, só com o texto fixo da categoria.
- termination_category string obrigatório
  Por que a equipe encerrou o servidor (vazio quando não foi encerrado pela equipe). Um de: "" (vazio), abuse, fraud, customer_request, internal_test, delinquency, other.
- user_data_sha256 string pode ser nulo
  SHA-256 (hex) do user data das instalações; o conteúdo nunca é devolvido. Nulo sem user data.
- user_data_size integer
  Tamanho do user data em bytes (0 sem user data).
next_cursor string pode ser nulo
Cursor da próxima página (nulo na última e sem paginação).

{
  "items": [
    {
      "cancel_at": null,
      "contract_id": "751e7c9a-fae2-4027-9be3-5728dfce8982",
      "created_at": "2026-10-20T18:00:00Z",
      "description": "Servidor de produção",
      "disk_layout": "raid1",
      "end_customer_ref": null,
      "external_id": null,
      "first_invoice_id": "36d56e13-ffa3-4af3-acc1-14aa538fb0ab",
      "hostname": "web-01",
      "id": "307d7f63-0f00-4d4b-bc28-839d359e13a3",
      "ipv4": "203.0.113.10",
      "ipv4_gateway": "203.0.113.1",
      "ipv4_prefix": 29,
      "monthly_cents": 79900,
      "operation": "deploy",
      "operation_id": "38b54c25-1f8d-40fe-8cb1-649ddb710f23",
      "os": {
        "code": "ubuntu-24.04",
        "family": "ubuntu",
        "id": "180cadfe-7099-445b-9dce-3a86af179a17",
        "install_method": "image",
        "login_user": "ubuntu",
        "name": "Ubuntu 24.04 LTS",
        "password_required": false,
        "raid1": true,
        "storage": {
          "default_filesystem": "",
          "filesystems": [],
          "levels": [
            {
              "even_disks": false,
              "filesystems": [],
              "level": "raid1",
              "max_disks": 2,
              "min_disks": 2
            }
          ]
        },
        "version": "24.04"
      },
      "password_login": false,
      "plan": {
        "active": true,
        "bandwidth_mbps": 0,
        "boot_slot": "",
        "code": "c1.small.ssd",
        "cores": 4,
        "cpu": "Intel(R) Xeon(R) CPU E3-1270 v6 @ 3.80GHz",
        "cpu_threads": 8,
        "created_at": "2026-10-20T18:00:00Z",
        "disk_slots": [
          {
            "id": "ssd-128-2",
            "model": "",
            "size_gb": 128,
            "type": "ssd"
          }
        ],
        "disks": [
          {
            "count": 2,
            "model": "",
            "size_gb": 128,
            "type": "ssd"
          }
        ],
        "id": "a30bf51c-7749-4ed5-8983-8201f864273b",
        "memory_gb": 32,
        "monthly_cents": 79900,
        "name": "c1.small.ssd · Supermicro X11",
        "port_speed_mbps": 1000,
        "product_id": "a3052a82-1c61-48d1-8feb-612bf80ff949",
        "raid1": true,
        "traffic_tb": 0
      },
      "power": "on",
      "site": {
        "active": true,
        "city": "Varginha",
        "code": "mg-1",
        "country": "BR",
        "created_at": "2026-10-20T18:00:00Z",
        "id": "4afc7034-1b53-4b2a-bc4c-d831d6e39028",
        "name": "Minas Gerais 01",
        "region_id": "7991b4f0-3bd8-47f3-bd3c-30b5d9ac664e"
      },
      "ssh_keys": 1,
      "status": "active",
      "steps": [
        {
          "finished_at": null,
          "message": "",
          "name": "prepare",
          "started_at": null,
          "status": "done"
        }
      ],
      "storage": {
        "disks": [
          {
            "id": "ssd-128-2",
            "model": "",
            "size_gb": 128,
            "type": "ssd"
          }
        ],
        "filesystem": "",
        "raid": "raid1",
        "summary": "ZFS RAID 1 em 2× SSD 128 GB"
      },
      "suspended_at": null,
      "tags": [
        "env=prod"
      ],
      "terminated_at": null,
      "termination_category": "",
      "user_data_sha256": "9f2c4e1b7a3d5f8e0c6b2a4d8e1f3a5c7b9d0e2f4a6c8e0b1d3f5a7c9e1b3d5f",
      "user_data_size": 92
    }
  ],
  "next_cursor": null
}

Erros

Todo erro vem como application/problem+json (RFC 9457), com um code estável, a mensagem em português em detail, o motivo de cada campo em errors (nos erros de validação) e o request_id, que você informa ao suporte. Veja a lista completa de códigos.

Status	Quando	Códigos
400	Requisição inválida (JSON malformado, campo desconhecido, parâmetro inválido ou falha de validação).	`validation_failed`, `invalid_cursor`
401	Não autenticado (token ausente, inválido ou expirado; credenciais inválidas).	`auth.unauthorized`
403	Autenticado, mas sem permissão para a área ou a operação.	`api_token.insufficient_scope`

{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "detail": "o token não tem o escopo servers:read; crie um token com esse escopo em Desenvolvedores › Tokens de API",
  "code": "api_token.insufficient_scope",
  "request_id": "6f1c0b2a9e4d7c3b5a8f0e1d"
}