VPS API Reference

Base URL

https://console.vrtxlabs.tech/api/v2

Successful responses wrap payloads in { "data": ... }. Errors return { "error": { "code", "message" } }.

Every request requires a Bearer token in the Authorization header. Generate a token from Account Settings → API.

Authorization: Bearer YOUR_API_TOKEN

Optional IP whitelisting is enforced when configured on your account. Requests from non-whitelisted IPs receive 403 IP_NOT_ALLOWED.

Typical workflow

Discover plans, regions & templates

Before creating a server, list available compute plans, datacenter locations, and OS templates for your chosen region.

# List plans
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://console.vrtxlabs.tech/api/v2/plans

# List locations
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://console.vrtxlabs.tech/api/v2/locations

# Templates for location 1
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://console.vrtxlabs.tech/api/v2/locations/1/templates

Plan ↔ API mapping

Use these plan_id values in POST /servers. Tiers match the Cloud VPS pricing page. Prices may change — confirm with GET /plans.

Region ↔ location_id

Pass location_id when creating a server. Regions align with the datacenter list on /vps. Availability varies — always validate with GET /locations before provisioning.

Create a server

Send plan_id, location_id, and template_slug. The platform selects the best node automatically. The server starts in installing status.

curl -X POST https://console.vrtxlabs.tech/api/v2/servers \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": 1,
    "location_id": 6,
    "template_slug": "ubuntu-24.04",
    "hostname": "app-01.example.com"
  }'

Poll until running

Poll GET /servers/{uuid}/status until the hypervisor reports running. Fetch root credentials from GET /servers/{uuid}/credentials once installation completes.

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://console.vrtxlabs.tech/api/v2/servers/SERVER_UUID/status

{
  "data": [
    {
      "id": 1,
      "name": "1 vCPU",
      "cpu": 1,
      "memory": 3221225472,
      "disk": 21474836480,
      "monthly_price": 3.92,
      "hourly_price": 0.0053
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 25,
    "total": 8
  }
}

{
  "plan_id": 1,
  "location_id": 3,
  "template_slug": "ubuntu-24.04",
  "hostname": "app-01.example.com"
}

{
  "data": {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "uuid_short": "a1b2c3d4",
    "name": "app-01.example.com",
    "status": "installing",
    "cpu": 1,
    "memory": 3221225472,
    "disk": 21474836480,
    "password_status": "generating",
    "operating_system": "Ubuntu 24.04 LTS",
    "ip_addresses": [
      {
        "address": "203.0.113.50",
        "type": "ipv4",
        "gateway": "203.0.113.1",
        "cidr": 24
      }
    ],
    "created_at": "2026-05-14T10:30:00+00:00"
  }
}

{
  "data": [
    {
      "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "uuid_short": "a1b2c3d4",
      "name": "app-01.example.com",
      "status": "installing",
      "cpu": 1,
      "memory": 3221225472
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 2,
    "per_page": 25,
    "total": 34
  }
}

{
  "data": {
    "state": "running",
    "status": null,
    "uptime_seconds": 86400
  }
}

{
  "data": {
    "password_status": "ready",
    "root_password": "generated-secret-password"
  }
}

Additional endpoints cover backups, security groups, SSH keys, power actions, and billing. See the full reference below.

Pagination

List endpoints return paginated collections. Pass ?page=N (1-based) to walk results. The meta object is always present on paginated responses.

Paginated endpoints: /plans/servers/servers/{uuid}/backups

GET https://console.vrtxlabs.tech/api/v2/servers?page=2&per_page=25

{
  "data": [ /* server objects */ ],
  "meta": {
    "current_page": 2,
    "last_page": 4,
    "per_page": 25,
    "total": 87
  }
}

API tokens are rate-limited per account. Limits apply across all tokens on the account unless noted otherwise.

Response headers

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1715684400
Retry-After: 42

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Retry after 42 seconds."
  }
}

Use retries with care on mutating endpoints. Reads are always safe to repeat; creates are not unless you supply an idempotency key.

Send Idempotency-Key: <unique-uuid> on POST /servers. The same key within 24 hours returns the original 201 response instead of creating a second server.

POST https://console.vrtxlabs.tech/api/v2/servers
Authorization: Bearer YOUR_API_TOKEN
Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7
Content-Type: application/json

{ "plan_id": 1, "location_id": 3, "template_slug": "ubuntu-24.04" }

• Retry GET and status polls with exponential backoff (e.g. 2s → 4s → 8s, cap at 30s) while status is installing.
• On 429, honour Retry-After before sending the next request.
• On 5xx, retry at most 3 times with jitter; do not retry 4xx except 429.
• Never retry POST /servers without Idempotency-Key unless you can tolerate duplicate resources.

Register HTTPS endpoints in the console to receive lifecycle events. Payloads are signed with HMAC-SHA256 (X-Vrtx-Signature header).

{
  "id": "evt_01j2k3m4n5p6q7r8",
  "type": "server.running",
  "created_at": "2026-05-14T10:35:12+00:00",
  "data": {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "uuid_short": "a1b2c3d4",
    "name": "app-01.example.com",
    "status": null,
    "state": "running"
  }
}

• Endpoints must return 2xx within 10 seconds.
• Failed deliveries are retried with exponential backoff for up to 72 hours.
• Verify signatures before acting on payload data.

Common errors