girginos
Developer API

A REST API that respects your time.

Bearer auth, idempotent writes, webhooks for every state change, and JSON from end to end. Same API that powers the console.

Endpoints
180+
Auth
Bearer
JWT / token
Rate limit
600rpm
per token
Webhooks
HMAC
sha256

Authentication

Every request takes an Authorization: Bearer header. Tokens are scoped to a tenant and can be rotated from the console.

curl -H "Authorization: Bearer $GIRGINOS_TOKEN" \
     https://center.girginos.net/v1/admin/inventory

Create a VM

Idempotent by client_token. Retry-safe across network blips.

curl -X POST https://center.girginos.net/v1/vms \
  -H "Authorization: Bearer $GIRGINOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-01",
    "vcpus": 4,
    "memory_mib": 8192,
    "disk_gib": 80,
    "image": "ubuntu-22.04",
    "network": "br-public",
    "cloud_init": "#cloud-config\nssh_authorized_keys: [ssh-ed25519 ...]"
  }'
Endpoints

A catalogue of what you can do.

Virtual machines

GET
/v1/vms
List all VMs
POST
/v1/vms
Create a VM (cloud-init aware)
GET
/v1/vms/{id}
Get VM detail + live state
POST
/v1/vms/{id}/start
Start the VM
POST
/v1/vms/{id}/snapshot
Take a crash-consistent snapshot
POST
/v1/vms/{id}/migrate
Live-migrate to another node
DELETE
/v1/vms/{id}
Destroy and clean up the VM

Networking & IPAM

GET
/v1/networks
List bridges, vSwitches, VPCs
POST
/v1/ipam/sync
Reconcile IPAM ↔ reservations
GET
/v1/ipam/leases
List active leases

Storage & HA

GET
/v1/storage/health
DRBD + disk health snapshot
POST
/v1/admin/ha/vm/{id}/prepare
Promote VM to HA (DRBD)
POST
/v1/admin/ha/vm/{id}/pause
Maintenance pause

Inventory & observability

GET
/v1/admin/inventory
Cluster-wide inventory snapshot
GET
/v1/admin/ha/history?limit=200
HA event history
GET
/v1/alerts/events?limit=200
Recent alert events

Webhooks for every state change

VM created, snapshot completed, HA failover, alert fired — delivered as signed POSTs (HMAC-SHA256). Retries with exponential backoff.

POST https://your.app/girginos
X-Girginos-Signature: sha256=ab12...
{
  "event": "vm.failover_restart",
  "vm_id": "9c1e...",
  "from_node": "node-a",
  "to_node":   "node-b",
  "downtime_ms": 1240,
  "ts": "2026-05-18T10:14:22Z"
}

CLI

The girginos CLI wraps the same REST API. Useful for scripts and CI.

# install
curl -sSL https://girginos.net/cli | sh

# auth
girginos login --token $GIRGINOS_TOKEN

# list & create
girginos vm list
girginos vm create --name web-01 --vcpus 4 --memory 8G

SDKs landing through beta

Go SDK ships in v1.1, TypeScript SDK in v1.2. Both are open source.

Get an API tokenRequest early SDK access