LiteVPS API

Base URL: https://api.litevps.dev/api  ·  openapi.json

Quick Start for Agents

1. Register via the portal and obtain a JWT

curl -s -X POST https://api.litevps.dev/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"agent@example.com","password":"s3cr3t"}' \
  | jq -r .token

2. Create a VPS

TOKEN="eyJ..."
curl -s -X POST /api/vps \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"my-vm","plan_id":"<plan-id>"}' \
  | jq '{id:.id, state:.state}'

3. Poll until state = "running"

VPS_ID="<id from step 2>"
while true; do
  STATE=$(curl -s /api/vps/$VPS_ID \
    -H "Authorization: Bearer $TOKEN" | jq -r .state)
  echo "state: $STATE"
  [ "$STATE" = "running" ] && break
  sleep 5
done

4. Execute a command

curl -s -X POST /api/vps/$VPS_ID/exec \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"command":"uname -a"}' \
  | jq '{stdout,stderr,exit_code,duration_ms}'

Authentication

All protected endpoints require one of:

• JWT — Authorization: Bearer <jwt> obtained from /api/auth/login
• Access token — Authorization: Bearer vtk_<token> created via POST /api/tokens

Balance errors (402)

When balance is insufficient the API returns HTTP 402:

{
  "error":    "insufficient balance",
  "balance":  0.0420,
  "required": 0.1667
}

Auth

# Body fields: email, password, cf-turnstile-response (required)
# Obtain a CAPTCHA token from the portal — direct curl registration is blocked.
# → 400 "CAPTCHA verification failed" if token is missing or invalid

curl -X POST /api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"password123"}'
# → {"token":"eyJ..."}

curl /api/me -H "Authorization: Bearer $TOKEN"
# → {"id":"...","email":"you@example.com","balance":10.5000}

Pricing

curl /api/pricing
# → [{"id":"...","name":"Nano","vcpu":1,"memory_mb":512,"disk_gb":10,"price_hourly":0.0042}]

VPS

curl -X POST /api/vps \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name":    "web-01",
    "plan_id": "plan-uuid",
    "ssh_key_ids": ["key-uuid"]
  }'

Snapshots

Agent-Ready Features

curl -X PUT "/api/vps/$VPS_ID/files?path=/root/hello.txt" \
  -H "Authorization: Bearer $TOKEN" \
  --data-binary @hello.txt

curl "/api/vps/$VPS_ID/files?path=/etc/hostname" \
  -H "Authorization: Bearer $TOKEN"

Exec / Background Jobs

# Synchronous
curl -X POST /api/vps/$VPS_ID/exec \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"command":"df -h /","timeout_seconds":30}'
# → {"stdout":"Filesystem ...","stderr":"","exit_code":0,"duration_ms":142}

# Asynchronous
curl -X POST /api/vps/$VPS_ID/exec \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"command":"apt-get update -y","timeout_seconds":300,"background":true}'
# → {"job_id":"...","status":"pending","timeout_seconds":300}

VM Templates

# Create a VPS from a template
curl -X POST /api/vps \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"agent-vm","template":"ubuntu-22-small"}'
# template fields (vcpu, memory_mb, disk_gb, user_data, ttl_minutes) are used
# as defaults; explicit request fields override them.

Batch Operations

curl -X POST /api/vps/batch \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"vms":[{"name":"w1","template":"ubuntu-22-small"},{"name":"w2","template":"ubuntu-22-small"}]}'
# → {"results":[{"index":0,"vps":{...}},{"index":1,"vps":{...}}]}

curl -X POST /api/vps/batch/exec \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"ids":["uuid1","uuid2"],"command":"uptime","timeout_seconds":10}'
# → {"results":[{"vps_id":"uuid1","stdout":"...","exit_code":0},...]}

SSH Keys

Billing

Billing is prepaid. Running VMs are charged per-minute based on their plan's hourly rate. Minimum top-up: $5.00. Maximum top-up: $50.00.

curl -X POST /api/billing/add-funds \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"amount":10}'
# → {"url":"https://checkout.stripe.com/..."}

Access Tokens

Access tokens (prefix vtk_) are long-lived alternatives to JWTs. Ideal for CI/CD pipelines and agents. Tokens can optionally have a spend limit.

curl -X POST /api/tokens \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"ci-deploy"}'
# → {"id":"...","name":"ci-deploy","token":"vtk_abc123..."}

Health

LiteVPS API  ·  openapi.json