API Reference

The VeloxaHost REST API lets you manage all platform resources programmatically. Base URL: https://console.veloxahost.com/api/v1

Authentication

All API requests require authentication via a Bearer token. Generate an API key from Settings → API Keys in the console.

curl https://console.veloxahost.com/api/v1/instances \
  -H "Authorization: Bearer veloxa_your_api_key_here"

API keys are scoped — you choose what permissions each key has:

Scope	Description
instances:read / instances:write	Instances, snapshots, backups, images and profiles
networks:read / networks:write	Networks, forwards, peers and address sets
firewalls:read / firewalls:write	Firewall policies (ACLs) and their rules
storage:read / storage:write	Storage pools, volumes and buckets
dns:read / dns:write	DNS zones and records
monitoring:read / monitoring:write	Metrics, alert rules, alert history and operations
ssh-keys:read / ssh-keys:write	SSH keys
api-keys:read / api-keys:write	API keys (a key can only create keys within its own scopes)
marketplace:read / marketplace:write	Marketplace apps and deployments
org:read / org:write	Organization and project settings
regions:read	Available regions
*	Full access (use carefully)

Error Responses

All errors return JSON with an error field:

HTTP/1.1 404 Not Found
{
  "error": "Instance 'my-instance' not found"
}

---

Instances API

GET /instances

List all instances in the current organization.

curl /api/v1/instances \
  -H "Authorization: Bearer veloxa_..."

POST /instances

Create a new instance.

curl -X POST /api/v1/instances \
  -H "Authorization: Bearer veloxa_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-prod-01",
    "type": "container",
    "image": "ubuntu/24.04",
    "cpu_limit": 2,
    "memory_limit_mb": 2048,
    "disk_size_gb": 20
  }'

GET /instances/{name}

Get details for a specific instance including status, IP addresses, and resource usage.

POST /instances/{name}/state

Perform a lifecycle action: start, stop, restart, freeze, unfreeze.

curl -X POST /api/v1/instances/web-prod-01/state \
  -H "Authorization: Bearer veloxa_..." \
  -d '{"action": "restart"}'

DELETE /instances/{name}

Permanently delete an instance. This cannot be undone. A running instance must be stopped first, or send {"force": true} to stop it as part of the delete.

---

Networks API

GET /networks

List all networks in the organization.

GET /firewalls

List all firewall policies.

POST /firewalls

Create a firewall policy with inbound/outbound rules.

---

Storage API

GET /storage/pools

List storage pools available to the organization.

POST /storage/pools/{pool}/volumes

Create a new storage volume.

curl -X POST /api/v1/storage/pools/default/volumes \
  -H "Authorization: Bearer veloxa_..." \
  -d '{
    "name": "db-data",
    "config": { "size": "50GiB" }
  }'

GET /storage/buckets

List S3-compatible storage buckets.

POST /storage/buckets

Create a bucket. Body: name (3-63 lowercase letters, numbers and hyphens, unique in the region; a taken name answers 409) and size, the bucket's size quota (required, e.g. "10GiB", at most your plan's disk allowance). Object storage is billed on the size quota. Access keys are created with POST /storage/buckets/<pool>/<name>/keys.

---

Monitoring API

GET /instances/{name}/metrics

Get current CPU, memory, and disk metrics for a named instance.

GET /alerts/rules

List alert rules for the organization.

POST /alerts/rules

Create an alert rule. Supported channels: email, slack, discord, webhook.

curl -X POST /api/v1/alerts/rules \
  -H "Authorization: Bearer veloxa_..." \
  -d '{
    "name": "High CPU",
    "metric": "cpu_percent",
    "condition": "gt",
    "threshold": 80,
    "channels": "email,slack",
    "cooldown_minutes": 15
  }'