Servers API Reference

Complete reference for the Servers API — list, create, start, stop, and destroy servers.

intermediate

10 min read

LightYear Team

Updated April 24, 2026

apiserversrestreference

Endpoints

Method	Path	Description
GET	/v1/servers	List all servers
POST	/v1/servers	Create a server
GET	/v1/servers/:id	Get server details
PATCH	/v1/servers/:id	Update server label
DELETE	/v1/servers/:id	Destroy a server
POST	/v1/servers/:id/start	Start a stopped server
POST	/v1/servers/:id/stop	Stop a running server
POST	/v1/servers/:id/reboot	Reboot a server

List Servers

>_BASH

$GET /v1/servers

>_BASH

$curl "https://api.lightyear.host/v1/servers"   -H "Authorization: Bearer <API_KEY>"

Response:

JSON

{
  "data": [
    {
      "id": "srv_abc123",
      "label": "ml-training-01",
      "status": "active",
      "region": "hkg",
      "plan": "gpu-a100-80",
      "main_ip": "203.0.113.10",
      "vcpus": 16,
      "ram_gb": 128,
      "disk_gb": 1000,
      "price_per_hour": "2.49",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ]
}

Create a Server

>_BASH

$POST /v1/servers
$Content-Type: application/json
$
${
$  "region": "hkg",
$  "plan": "gpu-a100-80",
$  "os": "ubuntu-22-04",
$  "label": "ml-training-01",
$  "ssh_key_ids": ["key_abc123"],
$  "backups": true,
$  "ddos_protection": false,
$  "user_data": "#!/bin/bash\napt-get update"
$}

Response: 201 Created

JSON

{
  "data": {
    "id": "srv_abc123",
    "status": "starting",
    ...
  }
}

Destroy a Server

>_BASH

$DELETE /v1/servers/srv_abc123

Response: 204 No Content

Warning: This permanently deletes the server and all its data. This action cannot be undone.

Server Status Values

Status	Description
starting	Being provisioned
active	Running normally
stopping	Shutting down
stopped	Powered off
rebooting	Restarting
error	Provisioning failed
terminated	Destroyed

Python SDK Example

PYTHON

import requests

API_KEY = "your-api-key"
BASE_URL = "https://api.lightyear.host/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# List servers
resp = requests.get(f"{BASE_URL}/servers", headers=HEADERS)
servers = resp.json()["data"]

# Create server
payload = {
    "region": "hkg",
    "plan": "gpu-a100-80",
    "os": "ubuntu-22-04",
    "label": "my-gpu-server",
}
resp = requests.post(f"{BASE_URL}/servers", json=payload, headers=HEADERS)
new_server = resp.json()["data"]
print(f"Created: {new_server['id']}")

Was this article helpful?