Redes privadas

GET /cloud/network/private-networks

Escopo do token: networks:read. Recurso: Redes privadas.

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

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

Go

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/network/private-networks?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))
}

Python

import os

import requests

resp = requests.get(
    "https://dash.halver.com.br/api/v1/cloud/network/private-networks?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.

Respostas

200

Redes privadas vivas.

Campos da resposta

• items array de object obrigatório
  • apply_error string obrigatório
  • created_at string (date-time) obrigatório
  • description string obrigatório
  • id string (uuid) obrigatório
  • region object obrigatório
    • code string obrigatório
    • id string (uuid) obrigatório
    • name string obrigatório
  • servers array de object obrigatório
    • address string obrigatório

      Endereço sugerido ao servidor na sub-rede.

    • apply_error string obrigatório

      Última resposta do switch a uma mudança que não passou (“” quando nenhuma).

    • hostname string obrigatório
    • id string (uuid) obrigatório
    • server_id string (uuid) obrigatório
    • status string obrigatório

      A porta do switch do servidor, configurada pelo job cloud-network: connecting = a VLAN indo para a porta; failed = o switch recusou ou não aplicou a tempo; removing = a VLAN saindo da porta. Um de: connecting, active, failed, removing.

  • status string obrigatório

    Um de: configuring, active, deleting, failed.

  • subnet string obrigatório

    Sub-rede da rede (ex. 10.240.0.0/24).

  • vlan_id integer obrigatório

    VID que o cliente configura no sistema (802.1Q).

• next_cursor string pode ser nulo

  Cursor da próxima página (nulo na última e sem paginação; ausente nas listas da equipe).

Exemplo de resposta

{
  "items": [
    {
      "apply_error": "",
      "created_at": "2026-10-20T18:00:00Z",
      "description": "Banco de dados",
      "id": "b7ad1a4c-5186-49fc-a761-c6de92f6ceea",
      "region": {
        "code": "br-mg-1",
        "id": "8c48d558-f6ba-472a-b7f4-e834d7d06d10",
        "name": "Minas Gerais"
      },
      "servers": [
        {
          "address": "198.51.100.20",
          "apply_error": "",
          "hostname": "web-01",
          "id": "6b7b19c5-375a-43fa-a24b-74fc1462808d",
          "server_id": "307d7f63-0f00-4d4b-bc28-839d359e13a3",
          "status": "connecting"
        }
      ],
      "status": "active",
      "subnet": "10.20.30.0/24",
      "vlan_id": 3001
    }
  ],
  "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

Exemplo de erro

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