Primeros pasos

Introducción

La API Panel KVM permite gestionar mediante programación los VPS KVM de su cuenta LWS: inventario, supervisión, alimentación, reinstalación, snapshots, copias de seguridad, cortafuegos, red y claves SSH. Ofrece lo mismo que el panel de cliente KVM, para sus scripts, su integración continua o su supervisión.

Inicio rápido

1. Cree su clave API. En el panel KVM, abra la página API / MCP, reservada a la cuenta principal. Declare la dirección IP desde la que se realizarán sus llamadas, active el acceso, genere la clave y elija los VPS que podrá controlar: todos o una selección. Una clave que aún no cubre ningún VPS funciona, pero su lista de VPS está vacía. La clave completa solo se muestra una vez: cópiela de inmediato.

2. Guárdela en una variable de entorno, como hacen todos los ejemplos de esta documentación:

export LWS_API_KEY="lws_live_sk_7Yc2Kp9RtNwQ4mZ8Bx3Vf1Hd6Ls0AjE2"

3. Compruebe que funciona:

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

La respuesta indica la cuenta, el nivel de permisos de la clave y el número de VPS que cubre.

4. Liste sus VPS:

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

Cada VPS se identifica por su vmid, que utilizará en todas las demás llamadas.

5. Lance una acción y sígala. Reinicie un 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"}'

La respuesta contiene una tarea ("id": "tsk_000002e1"). Consúltela hasta que su estado sea succeeded:

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

Autenticación

Cada petición incluye la clave en el encabezado Authorization, con el esquema Bearer. No la transmita nunca en una URL: los registros de acceso conservan las direcciones.

La clave se configura desde la página API / MCP del panel:

• Direcciones autorizadas (obligatorio): IPv4, IPv6 o rangos CIDR. El acceso no puede activarse sin al menos una dirección. Una llamada procedente de otra dirección se rechaza (403 ip_not_allowed).
• Activación: un interruptor corta el acceso sin eliminar la clave (401 access_disabled).
• Regeneración: una nueva clave invalida la anterior de inmediato, y se avisa por correo electrónico al titular de la cuenta.

Permisos y alcance

Cada clave recibe un nivel de permisos:

El nivel requerido figura al principio de cada operación. Una llamada que supera el nivel concedido se rechaza (403 insufficient_scope), y la respuesta indica el nivel exigido en required_level.

El nivel se elige en la página API / MCP del panel. El paso al nivel Completo debe confirmarse mediante un código enviado por correo electrónico al titular de la cuenta; volver a un nivel inferior no lo requiere.

El alcance de la clave cubre todos los VPS de la cuenta, incluidos los que se contraten más adelante, o bien una selección de VPS. Un VPS fuera del alcance responde exactamente igual que un VPS inexistente (404 vm_not_found).

Peticiones y respuestas

• Los intercambios se realizan en JSON, codificado en UTF-8. Los cuerpos de las peticiones se envían con Content-Type: application/json.
• Un recurso se devuelve dentro de data.
• Una lista se devuelve dentro de data, acompañada de un bloque meta. Las listas largas (VPS, tareas, registro de actividad) se paginan con page (por defecto 1) y per_page (por defecto 25, como máximo 100); las listas cortas se devuelven completas.
• Las fechas siguen el formato ISO 8601 con desfase horario: 2027-03-14T00:00:00+01:00.
• Los volúmenes se expresan en bytes, salvo min_memory_gb en el catálogo de sistemas.
• Los identificadores son cadenas, incluido vmid: "116807". Solo account_id, en GET /me, es un número.
• Cada respuesta incluye un encabezado X-Request-Id. Indíquelo al soporte de LWS en cualquier incidencia: permite localizar la llamada exacta.

{
  "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 }
}

Operaciones asíncronas

Las operaciones marcadas como [Differed] (arranque, reinstalación, snapshot, copia de seguridad, cortafuegos…) no se ejecutan durante la petición: se ponen en cola y responden 202 Accepted con la tarea creada.

{
  "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
      }
    ]
  }
}

A continuación, siga la tarea con Consultar una tarea cada pocos segundos, hasta que status sea succeeded o failed. Consultarla con más frecuencia no acelera nada y consume su cuota.

Solo puede ejecutarse a la vez una operación de un mismo tipo en un VPS: una segunda solicitud se rechaza (409 task_already_running) y la respuesta identifica la tarea en curso en task_id.

Un VPS bloqueado por el hipervisor también rechaza las escrituras (409 server_locked). El campo reason indica qué hacer: operation_in_progress, hay una operación en curso, vuelva a intentarlo tras el plazo del encabezado Retry-After; suspended, el VPS está en hibernación, arránquelo primero; support_notified, el bloqueo es anómalo, el equipo de LWS ha sido avisado y está interviniendo, no tiene sentido reintentar en bucle.

Durante una intervención anunciada por LWS en el servidor anfitrión de un VPS (actualización, reinicio…), si dicho servidor deja de responder, se rechazan las escrituras en ese VPS y las lecturas que consultan el hipervisor (503 server_maintenance). El campo maintenance de la respuesta precisa su naturaleza y el fin previsto, y el encabezado Retry-After, el plazo recomendado antes de reintentar. El inventario y la ficha del VPS siguen respondiendo, con status: maintenance.

Las demás escrituras (imágenes ISO, DNS inverso, contraseña root, claves SSH, conjuntos de reglas) son inmediatas y devuelven directamente su resultado.

Errores

Los errores se devuelven en 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"
}

Base su tratamiento en code, que es estable. detail está dirigido a una persona y puede cambiar. Según el error, la respuesta también incluye errors (detalle por parámetro), required_level, task_id, lock y reason, o retry_after.

Cuotas

Las llamadas se limitan por cuenta, en una ventana deslizante de una hora, según tres familias independientes:

Una operación pesada está sujeta a dos límites: el del VPS afectado y el de la cuenta. El límite por VPS evita que un mismo servidor se solicite en bucle, sin penalizar a las cuentas con muchos VPS; el mensaje de rechazo indica cuál de los dos límites se ha alcanzado.

Para no sobrecargar los hipervisores, el estado y las métricas instantáneas de un VPS se almacenan en caché durante 15 segundos, y el historial de métricas entre 1 minuto y 1 hora según el período. Consultar con más frecuencia devuelve el mismo valor y consume cuota sin aportar nada.

Las respuestas a las llamadas autenticadas indican el estado de la cuota en los encabezados X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Una llamada autenticada pero rechazada (parámetro no válido, nivel insuficiente, conflicto…) también consume cuota; una llamada rechazada en la autenticación, dirigida a una ruta inexistente o rechazada por exceso de cuota (429) no la consume. Una vez alcanzado el límite, la API responde 429 rate_limited: espere el número de segundos indicado en el encabezado Retry-After antes de volver a intentarlo.