List VPS

GET /api/v1/servers

operationIdgetServers

Required level: Read only
Rate limit: read, 3,600 calls per hour

Inventory of the VPS covered by the key. The power status is read from the hypervisor; if it is temporarily unreachable, status is unavailable and the rest of the record remains usable.

During an intervention announced by LWS on the host server (update, reboot…), maintenance gives its nature and schedule, whether it is scheduled or in progress. If the host server stops responding during that intervention, status is maintenance: a planned, temporary unavailability, not an outage.

The status filter applies to the requested page: meta describes the full, unfiltered inventory, so a filtered page may contain fewer entries than per_page.

The state read from the hypervisor is cached for 15 seconds: a closer call returns the same value. Any write made through the API on a VPS refreshes its state immediately.

Query parameters

page integer optional: Requested page. A value below 1 is raised to 1.

at least 1
per_page integer optional: Page size. A value above 100 is capped at 100; a zero, negative or non-numeric value falls back to 25.

at most 100 at least 1
status string optional: Keep only the VPS in this state (applied to the returned page).

one of: running, stopped, unavailable, maintenance

Responses

200

A page of the inventory

{
  "data": [
    {
      "vmid": "116807",
      "name": "vps116807",
      "node": "shp-40",
      "status": "running",
      "maintenance": null,
      "os_template": "debian12_64",
      "commercial_name": "Debian 12",
      "ipv4": "31.207.34.214",
      "ipv6": "2a00:7ee0:9:1:11:6807:1:1",
      "additional_ips": [
        "51.83.12.98"
      ],
      "datacenter": {
        "code": "SJ1",
        "city": "Nancy",
        "country": "France",
        "zone": "eu-france-est"
      },
      "purchased_at": "2025-03-14T00:00:00+01:00",
      "expires_at": "2027-03-14T00:00:00+01:00",
      "enabled": true,
      "expired": false,
      "comment": null
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1
  }
}

Response fields 30

data object[]

required
vmid string

Identifier of the VPS

Example: 116807
name string

Name of the machine on the hypervisor
node string

Hypervisor hosting the VPS, for information only. Never requested as input, and may change during a migration.
status string

Power status; unavailable if the hypervisor did not respond; maintenance if it does not respond during an intervention announced by LWS

one of: running, stopped, unavailable, maintenance Example: running
maintenance object

Intervention announced by LWS on the host server (service status), scheduled or in progress, whether the server responds or not; null if there is none
status string

scheduled: scheduled; in_progress: in progress

one of: scheduled, in_progress
kind string

works: maintenance, improvement or reboot; incident: incident, disruption, slowdown or attack

one of: works, incident
starts_at string (date-time)
expected_end string (date-time)

Expected end; always null for an incident
os_template string
commercial_name string
ipv4 string
ipv6 string
additional_ips string[]
datacenter object

Datacenter
code string

Example: SJ1
city string

Example: Nancy
country string

Example: France
zone string

Example: eu-france-est
purchased_at string (date-time)
expires_at string (date-time)
enabled boolean

false: service disabled
expired boolean

true: service expired
comment string

Comment entered in the panel
meta object

Pagination. Non-paginated lists return everything and meta reflects the number returned.

PaginationMeta

required
page integer (int64)

Page returned

Example: 1
per_page integer (int64)

Page size

Example: 25
total integer (int64)

Total number of items

Example: 887
total_pages integer (int64)

Total number of pages

Example: 36

400

Invalid parameters: validation_failed — status not in the accepted list.

{
  "type": "https://docs.lws.fr/kvm/errors/validation-failed",
  "title": "Paramètres invalides",
  "status": 400,
  "code": "validation_failed",
  "detail": "Paramètre « status » invalide.",
  "request_id": "3f9a1c07b2e45d18",
  "errors": {
    "status": "Valeurs acceptées : running, stopped, unavailable, maintenance."
  }
}

Response fields 18

type string (uri)

Example: https://docs.lws.fr/kvm/errors/vm-not-found

required
title string

Short title, in French

Example: VPS introuvable

required
status integer (int64)

HTTP status

Example: 404

required
code string

Stable machine-readable code (see "Errors" in Getting started)

Example: vm_not_found

required
detail string

Detailed message, in French

Example: Aucun VPS 999999 sur ce compte.

required
request_id string

Identifier of the request, to give to support

Example: 3f9a1c07b2e45d18

required
errors object

validation_failed: message per faulty parameter
required_level string

insufficient_scope: level required by the operation

one of: read, exploitation, full
task_id string

task_already_running: task running on this VPS

Example: tsk_000002d5
family string

rate_limited: exhausted rate limit family

one of: read, mutation, heavy
limit integer (int64)

rate_limited: hourly limit of the family
retry_after integer (int64)

rate_limited: seconds to wait
lock string

server_locked: lock set by the hypervisor (backup, snapshot, suspended…)

Example: snapshot
reason string

server_locked: operation_in_progress, an operation is running, retry after Retry-After; suspended, the VPS is hibernating, start it first; support_notified, abnormal lock, the LWS team has been notified and is taking care of it

one of: operation_in_progress, suspended, support_notified
maintenance object

server_maintenance: nature of the intervention, start and expected end (null for an incident)
kind string

one of: works, incident
started_at string (date-time)
expected_end string (date-time)

401

Authentication refused: invalid_token — Authorization header missing or malformed, or unknown key; access_disabled — API access turned off for this account, or API service temporarily turned off by LWS.

Authorization header missing or malformed, or unknown key

{
  "type": "https://docs.lws.fr/kvm/errors/invalid-token",
  "title": "Authentification invalide",
  "status": 401,
  "code": "invalid_token",
  "detail": "Clé inconnue ou révoquée.",
  "request_id": "3f9a1c07b2e45d18"
}

API access turned off for this account, or API service temporarily turned off by LWS

{
  "type": "https://docs.lws.fr/kvm/errors/access-disabled",
  "title": "Accès API désactivé",
  "status": 401,
  "code": "access_disabled",
  "detail": "L'accès API est désactivé pour ce compte. Réactivez-le depuis la page « API / MCP » du panel.",
  "request_id": "3f9a1c07b2e45d18"
}

Response fields 18

type string (uri)

Example: https://docs.lws.fr/kvm/errors/vm-not-found

required
title string

Short title, in French

Example: VPS introuvable

required
status integer (int64)

HTTP status

Example: 404

required
code string

Stable machine-readable code (see "Errors" in Getting started)

Example: vm_not_found

required
detail string

Detailed message, in French

Example: Aucun VPS 999999 sur ce compte.

required
request_id string

Identifier of the request, to give to support

Example: 3f9a1c07b2e45d18

required
errors object

validation_failed: message per faulty parameter
required_level string

insufficient_scope: level required by the operation

one of: read, exploitation, full
task_id string

task_already_running: task running on this VPS

Example: tsk_000002d5
family string

rate_limited: exhausted rate limit family

one of: read, mutation, heavy
limit integer (int64)

rate_limited: hourly limit of the family
retry_after integer (int64)

rate_limited: seconds to wait
lock string

server_locked: lock set by the hypervisor (backup, snapshot, suspended…)

Example: snapshot
reason string

server_locked: operation_in_progress, an operation is running, retry after Retry-After; suspended, the VPS is hibernating, start it first; support_notified, abnormal lock, the LWS team has been notified and is taking care of it

one of: operation_in_progress, suspended, support_notified
maintenance object

server_maintenance: nature of the intervention, start and expected end (null for an incident)
kind string

one of: works, incident
started_at string (date-time)
expected_end string (date-time)

403

Access denied: ip_not_allowed — calling address not authorized.

{
  "type": "https://docs.lws.fr/kvm/errors/ip-not-allowed",
  "title": "Adresse non autorisée",
  "status": 403,
  "code": "ip_not_allowed",
  "detail": "L'adresse 203.0.113.10 ne figure pas parmi les adresses autorisées de ce compte.",
  "request_id": "3f9a1c07b2e45d18"
}

Response fields 18

type string (uri)

Example: https://docs.lws.fr/kvm/errors/vm-not-found

required
title string

Short title, in French

Example: VPS introuvable

required
status integer (int64)

HTTP status

Example: 404

required
code string

Stable machine-readable code (see "Errors" in Getting started)

Example: vm_not_found

required
detail string

Detailed message, in French

Example: Aucun VPS 999999 sur ce compte.

required
request_id string

Identifier of the request, to give to support

Example: 3f9a1c07b2e45d18

required
errors object

validation_failed: message per faulty parameter
required_level string

insufficient_scope: level required by the operation

one of: read, exploitation, full
task_id string

task_already_running: task running on this VPS

Example: tsk_000002d5
family string

rate_limited: exhausted rate limit family

one of: read, mutation, heavy
limit integer (int64)

rate_limited: hourly limit of the family
retry_after integer (int64)

rate_limited: seconds to wait
lock string

server_locked: lock set by the hypervisor (backup, snapshot, suspended…)

Example: snapshot
reason string

server_locked: operation_in_progress, an operation is running, retry after Retry-After; suspended, the VPS is hibernating, start it first; support_notified, abnormal lock, the LWS team has been notified and is taking care of it

one of: operation_in_progress, suspended, support_notified
maintenance object

server_maintenance: nature of the intervention, start and expected end (null for an incident)
kind string

one of: works, incident
started_at string (date-time)
expected_end string (date-time)

429

Rate limit exceeded: rate_limited — hourly limit of the family exhausted.

{
  "type": "https://docs.lws.fr/kvm/errors/rate-limited",
  "title": "Quota dépassé",
  "status": 429,
  "code": "rate_limited",
  "detail": "Quota dépassé pour les opérations de type « read » : 3600 appels par heure. Réessayez dans 37 seconde(s).",
  "request_id": "3f9a1c07b2e45d18",
  "family": "read",
  "limit": 3600,
  "retry_after": 37
}

Response fields 18

type string (uri)

Example: https://docs.lws.fr/kvm/errors/vm-not-found

required
title string

Short title, in French

Example: VPS introuvable

required
status integer (int64)

HTTP status

Example: 404

required
code string

Stable machine-readable code (see "Errors" in Getting started)

Example: vm_not_found

required
detail string

Detailed message, in French

Example: Aucun VPS 999999 sur ce compte.

required
request_id string

Identifier of the request, to give to support

Example: 3f9a1c07b2e45d18

required
errors object

validation_failed: message per faulty parameter
required_level string

insufficient_scope: level required by the operation

one of: read, exploitation, full
task_id string

task_already_running: task running on this VPS

Example: tsk_000002d5
family string

rate_limited: exhausted rate limit family

one of: read, mutation, heavy
limit integer (int64)

rate_limited: hourly limit of the family
retry_after integer (int64)

rate_limited: seconds to wait
lock string

server_locked: lock set by the hypervisor (backup, snapshot, suspended…)

Example: snapshot
reason string

server_locked: operation_in_progress, an operation is running, retry after Retry-After; suspended, the VPS is hibernating, start it first; support_notified, abnormal lock, the LWS team has been notified and is taking care of it

one of: operation_in_progress, suspended, support_notified
maintenance object

server_maintenance: nature of the intervention, start and expected end (null for an incident)
kind string

one of: works, incident
started_at string (date-time)
expected_end string (date-time)

502

Dependency unreachable: upstream_unavailable — VPS inventory temporarily unavailable.

{
  "type": "https://docs.lws.fr/kvm/errors/upstream-unavailable",
  "title": "Service momentanément indisponible",
  "status": 502,
  "code": "upstream_unavailable",
  "detail": "Inventaire des VM indisponible.",
  "request_id": "3f9a1c07b2e45d18"
}

Response fields 18

type string (uri)

Example: https://docs.lws.fr/kvm/errors/vm-not-found

required
title string

Short title, in French

Example: VPS introuvable

required
status integer (int64)

HTTP status

Example: 404

required
code string

Stable machine-readable code (see "Errors" in Getting started)

Example: vm_not_found

required
detail string

Detailed message, in French

Example: Aucun VPS 999999 sur ce compte.

required
request_id string

Identifier of the request, to give to support

Example: 3f9a1c07b2e45d18

required
errors object

validation_failed: message per faulty parameter
required_level string

insufficient_scope: level required by the operation

one of: read, exploitation, full
task_id string

task_already_running: task running on this VPS

Example: tsk_000002d5
family string

rate_limited: exhausted rate limit family

one of: read, mutation, heavy
limit integer (int64)

rate_limited: hourly limit of the family
retry_after integer (int64)

rate_limited: seconds to wait
lock string

server_locked: lock set by the hypervisor (backup, snapshot, suspended…)

Example: snapshot
reason string

server_locked: operation_in_progress, an operation is running, retry after Retry-After; suspended, the VPS is hibernating, start it first; support_notified, abnormal lock, the LWS team has been notified and is taking care of it

one of: operation_in_progress, suspended, support_notified
maintenance object

server_maintenance: nature of the intervention, start and expected end (null for an incident)
kind string

one of: works, incident
started_at string (date-time)
expected_end string (date-time)

List VPS

Query parameters

Responses

Report an error

AI assistant