Primeiros passos

Introdução

A API Panel KVM permite gerir por programação os VPS KVM da sua conta LWS: inventário, monitorização, alimentação, reinstalação, snapshots, cópias de segurança, firewall, rede e chaves SSH. Reproduz o que o painel de cliente KVM permite fazer, para os seus scripts, a sua integração contínua ou a sua monitorização.

Início rápido

1. Crie a sua chave de API. No painel KVM, abra a página API / MCP, reservada à conta principal. Indique o endereço IP a partir do qual serão feitas as suas chamadas, ative o acesso, gere a chave e, em seguida, escolha os VPS que ela poderá gerir: todos ou uma seleção. Uma chave que ainda não abrange nenhum VPS funciona, mas a sua lista de VPS está vazia. A chave só é apresentada por inteiro uma única vez: copie-a de imediato.

2. Guarde-a numa variável de ambiente, tal como fazem todos os exemplos desta documentação:

export LWS_API_KEY="lws_live_sk_7Yc2Kp9RtNwQ4mZ8Bx3Vf1Hd6Ls0AjE2"

3. Verifique se funciona:

curl https://panelkvm.lwspanel.com/api/v1/me \
  -H "Authorization: Bearer $LWS_API_KEY"

A resposta indica a conta, o nível de permissão da chave e o número de VPS que ela abrange.

4. Liste os seus VPS:

curl https://panelkvm.lwspanel.com/api/v1/servers \
  -H "Authorization: Bearer $LWS_API_KEY"

Cada VPS é identificado pelo seu vmid, que irá reutilizar em todas as outras chamadas.

5. Execute uma ação e acompanhe-a. Reinicie um VPS:

curl -X POST https://panelkvm.lwspanel.com/api/v1/servers/116807/power \
  -H "Authorization: Bearer $LWS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "reboot"}'

A resposta contém uma tarefa ("id": "tsk_000002e1"). Consulte-a até o seu estado ser succeeded:

curl https://panelkvm.lwspanel.com/api/v1/tasks/tsk_000002e1 \
  -H "Authorization: Bearer $LWS_API_KEY"

Autenticação

Cada pedido transporta a chave no cabeçalho Authorization, segundo o esquema Bearer. Nunca a transmita num URL: os registos de acesso guardam os endereços.

A chave configura-se na página API / MCP do painel:

• Endereços autorizados (obrigatório): IPv4, IPv6 ou intervalos CIDR. O acesso não pode ser ativado sem pelo menos um endereço. Uma chamada proveniente de outro endereço é recusada (403 ip_not_allowed).
• Ativação: um interruptor corta o acesso sem eliminar a chave (401 access_disabled).
• Regeneração: uma nova chave invalida a anterior de imediato, e o titular da conta é avisado por e-mail.

Permissões e âmbito

Cada chave recebe um nível de permissão:

O nível exigido figura no início de cada operação. Uma chamada acima do nível concedido é recusada (403 insufficient_scope), e a resposta indica o nível exigido em required_level.

O nível escolhe-se na página API / MCP do painel. A passagem para o nível Completo tem de ser confirmada por um código enviado por e-mail ao titular da conta; regressar a um nível inferior não o exige.

O âmbito da chave abrange todos os VPS da conta, incluindo os adquiridos posteriormente, ou uma seleção de VPS. Um VPS fora do âmbito responde exatamente como um VPS inexistente (404 vm_not_found).

Pedidos e respostas

• As trocas fazem-se em JSON, codificado em UTF-8. Os corpos dos pedidos são enviados com Content-Type: application/json.
• Um recurso é devolvido em data.
• Uma lista é devolvida em data, acompanhada de um bloco meta. As listas longas (VPS, tarefas, registo de atividade) são paginadas por page (predefinição 1) e per_page (predefinição 25, no máximo 100); as listas curtas são devolvidas na totalidade.
• As datas seguem o formato ISO 8601 com fuso horário: 2027-03-14T00:00:00+01:00.
• Os volumes são expressos em bytes, com exceção de min_memory_gb no catálogo de sistemas.
• Os identificadores são cadeias de caracteres, incluindo vmid: "116807". Apenas account_id, em GET /me, é um número.
• Cada resposta inclui um cabeçalho X-Request-Id. Comunique-o ao suporte LWS em qualquer reporte: permite encontrar a chamada exata.

{
  "data": [
    {
      "id": "tsk_000002e1",
      "status": "succeeded",
      "action": "server.reboot",
      "vmid": "116807",
      "description": "Demande de reboot du serveur VPS-116807",
      "created_at": "2026-08-20T14:31:02+02:00",
      "finished_at": "2026-08-20T14:31:40+02:00"
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 }
}

Operações assíncronas

As operações marcadas com [Differed] (arranque, reinstalação, snapshot, cópia de segurança, firewall…) não são executadas durante o pedido: são colocadas em fila e respondem 202 Accepted com a tarefa criada.

{
  "data": {
    "tasks": [
      {
        "id": "tsk_000002e1",
        "status": "pending",
        "action": "server.reboot",
        "vmid": "116807",
        "description": "Demande de reboot du serveur VPS-116807",
        "created_at": "2026-08-20T14:31:02+02:00",
        "finished_at": null
      }
    ]
  }
}

Acompanhe depois a tarefa com Consultar uma tarefa, a cada poucos segundos, até status ser succeeded ou failed. Consultar com mais frequência não acelera nada e consome a sua quota.

Só pode ser executada uma operação do mesmo tipo de cada vez num VPS: um segundo pedido é recusado (409 task_already_running) e a resposta indica a tarefa em curso em task_id.

Um VPS bloqueado pelo hipervisor também recusa as escritas (409 server_locked). O campo reason indica o que fazer: operation_in_progress, há uma operação em curso, tente novamente após o prazo do cabeçalho Retry-After; suspended, o VPS está em hibernação, inicie-o primeiro; support_notified, o bloqueio é anómalo, a equipa LWS foi avisada e está a intervir, não vale a pena tentar repetidamente.

Durante uma intervenção anunciada pela LWS no servidor anfitrião de um VPS (atualização, reinício…), se esse servidor deixar de responder, as escritas nesse VPS e as leituras que consultam o hipervisor são recusadas (503 server_maintenance). O campo maintenance da resposta indica a sua natureza e o fim previsto, e o cabeçalho Retry-After o prazo aconselhado antes de tentar novamente. O inventário e a ficha do VPS continuam a responder, com status: maintenance.

As restantes escritas (imagens ISO, DNS reverso, palavra-passe root, chaves SSH, conjuntos de regras) são imediatas e devolvem diretamente o seu resultado.

Erros

Os erros são devolvidos no formato application/problem+json:

{
  "type": "https://docs.lws.fr/kvm/errors/vm-not-found",
  "title": "VPS introuvable",
  "status": 404,
  "code": "vm_not_found",
  "detail": "Aucun VPS 999999 sur ce compte.",
  "request_id": "3f9a1c07b2e45d18"
}

Baseie o seu tratamento em code, que é estável. detail destina-se a um humano e pode mudar. Consoante o erro, a resposta inclui também errors (detalhe por parâmetro), required_level, task_id, lock e reason, ou retry_after.

Quotas

As chamadas são limitadas por conta, numa janela deslizante de uma hora, segundo três famílias independentes:

Uma operação pesada está sujeita a dois limites: o do VPS visado e o da conta. O limite por VPS evita que um mesmo servidor seja solicitado em ciclo, sem penalizar as contas com muitos VPS; a mensagem de recusa indica qual dos dois limites foi atingido.

Para poupar os hipervisores, o estado e as métricas instantâneas de um VPS são guardados em cache durante 15 segundos, e o histórico de métricas entre 1 minuto e 1 hora consoante o período. Consultar com mais frequência devolve o mesmo valor e consome quota sem qualquer benefício.

As respostas às chamadas autenticadas indicam o estado da quota nos cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Uma chamada autenticada mas recusada (parâmetro inválido, nível insuficiente, conflito…) também consome crédito; uma chamada rejeitada na autenticação, dirigida a uma rota inexistente ou recusada por excesso (429) não consome. Atingido o limite, a API responde 429 rate_limited: aguarde o número de segundos indicado pelo cabeçalho Retry-After antes de tentar novamente.