REST API
Everything you can do in the portal's VM pages, as HTTP. Same roles, same quotas, same audit log.
Authentication
Create an API key under Profile → API keys. A key acts with its owner's permissions, can be limited to scopes and projects, and every call is written to the activity log.
shell
curl https://verlocx.example.com/api/v1/projects \ -H "Authorization: Bearer hx_…"# or: -H "X-Api-Key: hx_…"Endpoints
Projects
| Path | What |
|---|---|
GET /api/v1/projects | Projects you can see |
GET · POST /api/v1/projects/{project}/vms | VMs of a project · create one (same rules as the New VM dialog) |
/api/v1/projects/{project}/clusters | Clusters the project may deploy to |
/api/v1/projects/{project}/templates | Templates the project may use, with their limits |
/api/v1/projects/{project}/usage | Resource usage and costs |
/api/v1/projects/{project}/activity | The project's audit log |
/api/v1/projects/{project}/alerts | Alert rules — list, create, change, delete |
A single VM
| Path | What |
|---|---|
GET · PATCH · DELETE /api/v1/vms/{id} | Details · resize, rename, owner, tags · delete |
/api/v1/vms/{id}/power | Start, shutdown, reboot, stop, suspend, resume |
/api/v1/vms/{id}/exec | Run a script in the guest through the agent |
/api/v1/vms/{id}/metrics | CPU, memory and disk usage |
/api/v1/vms/{id}/snapshots | List and create; …/{name} deletes, …/{name}/restore rolls back |
/api/v1/vms/{id}/backups | Backups of the VM; …/restore restores one |
/api/v1/vms/{id}/nics | Network interfaces |
/api/v1/vms/{id}/firewall | Firewall state and …/rules |
/api/v1/vms/{id}/lease | Lease of the VM — read or extend |
API keys
| Path | What |
|---|---|
/api/v1/api-keys | Your keys — list, create; …/{id}/revoke revokes one |
Example: create a VM
shell
curl -X POST https://verlocx.example.com/api/v1/projects/{project}/vms \ -H "Authorization: Bearer hx_…" -H "Content-Type: application/json" \ -d '{ "clusterId": "…", "templateId": "…", "name": "web-prod-2105", "vcpu": 4, "memoryGb": 8, "diskGb": 80, "tags": ["web", "prod"] }'A name that carries a number —
web-prod-2105 — also asks for that VMID. If it's taken, blocked or outside the template's range, the request is refused with the reason (409), never placed on another ID. Optional fields: network, vlan, ip, owner.Errors
| Status | Meaning |
|---|---|
400 | Invalid input — the message says which field |
401 / 403 | No valid key, or the key lacks the permission or scope |
404 | Not found — or not visible to you |
409 | Conflict, e.g. the VMID from the name can't be used |
423 | The VM is locked by a running configuration run |
More examples
Reboot a VM
shell
curl -X POST https://verlocx.example.com/api/v1/vms/{id}/power \ -H "Authorization: Bearer hx_…" -H "Content-Type: application/json" \ -d '{ "action": "reboot" }' # start · shutdown · stop · reboot · suspend · resumeRun a script in the guest
shell
curl -X POST https://verlocx.example.com/api/v1/vms/{id}/exec \ -H "Authorization: Bearer hx_…" -H "Content-Type: application/json" \ -d '{ "shell": "powershell", "script": "Get-Service W32Time", "timeoutSecs": 60 }'Or run a preset by its id with { "presetId": "…" }.
Take a snapshot before a change
shell
curl -X POST https://verlocx.example.com/api/v1/vms/{id}/snapshots \ -H "Authorization: Bearer hx_…" -H "Content-Type: application/json" \ -d '{ "name": "pre-upgrade", "description": "before app 2.4", "withRam": false }'Give a VM a lease
shell
curl -X POST https://verlocx.example.com/api/v1/vms/{id}/lease \ -H "Authorization: Bearer hx_…" -H "Content-Type: application/json" \ -d '{ "days": 30 }'GET reads the lease, PUT changes it, DELETE removes it. A lease can also take an exact expiresAt and an expiryAction.
Next up