Management API Reference
Every Stratum node runs a local management API so you can manage that node's
networking yourself, from your own tooling. The full management surface is the
REST API over HTTPS on port 7070, alongside a gRPC health endpoint
on 7071 and a WebSocket event stream on 7072 — sharing one
authentication model and one TLS certificate.
This page is the complete REST reference, plus the WebSocket event stream and the gRPC health endpoint. The base URL is:
https://<node-ip>:7070
All REST paths below are relative to this base and live under the /api/v1
prefix.
Getting started
1. The API is off until you set a token
The management API is disabled by default and fails closed: the agent
will never serve these endpoints unauthenticated. It starts listening only when
an API token is configured. With no token the API is cleanly disabled, and
you manage the node through the panel and the local cenvero-str-ctl socket
instead.
Ask the node for a token whenever you need one:
sudo cenvero-str-ctl api-token generate
It prints the token once — store it then, because it is not shown again. To choose the value yourself, pipe it in so it never reaches your shell history:
printf '%s' "$MY_TOKEN" | sudo cenvero-str-ctl api-token set
cenvero-str-ctl api-token status # is one set? (never prints the value)
cenvero-str-ctl api-token clear # remove it — the API stops at the next restart
The token is stored root-only on the node, in your local overrides, so a later
panel sync does not discard it. You can also have the installer mint one up
front with CENVERO_API_TOKEN=auto.
Installed with Compute? The compute and suite installer profiles turn the
API on for you: they generate the token (stored root-only in
/etc/cenvero-str/api-token, never printed), because the
web console that runs your machines lives on the
API. The installer ends by printing the console's address. To install a
compute or suite node with the API off, set CENVERO_API_TOKEN=off. The
fabric profile leaves the API off unless you ask for it.
It is not settable with cenvero-str-ctl config set — that command
deliberately refuses credential keys, because a value passed as a command
argument ends up in shell history. api-token exists for exactly this reason.
A new or changed token takes effect when the agent restarts
(systemctl restart cenvero-stratum). The API listens only when all three
hold: a token is configured, service rest is on, and a TLS certificate is
available (TLS is mandatory — the agent refuses to serve plaintext). You can move
or gate the listener without removing the token:
cenvero-str-ctl config set api_bind_address 10.0.0.5 # bind to a management IP
cenvero-str-ctl service rest off # stop serving REST
cenvero-str-ctl service rest on # serve it again
cenvero-str-ctl service status # show each service's state
2. Authenticate with a bearer token
Send the token in the Authorization header on every protected call:
Authorization: Bearer <token>
These credentials are accepted, depending on the transport:
| Credential | How you get it | Scope | Works on |
|---|---|---|---|
| Node API token | The api_token you configured on the node | Full (node-wide) | REST, WebSocket, gRPC |
API token (cst_…) | cenvero-str-ctl token add <account> <name>, or POST /api/v1/access/users/{id}/tokens (secret shown once) | What its permissions give it, never more than its account (see Access control) | REST only |
Operator API key (csk_…) | cenvero-str-ctl apikeys mint <label> (secret shown once) | Full (Administrator on /), unless you narrow it: it is an API token of the built-in account apikeys@local | REST only |
| Tenant-scoped key | POST /api/v1/tenant/{id}/keys (see Multi-tenancy below) | Confined to one tenant | REST only |
People sign in to the web console with their own accounts; scripts use API tokens. An API token or operator key answers only what its permissions allow, exactly as the account's own sign-in would: see Access control for the refusals. A token is never accepted in the address, only in the header.
A tenant-scoped key may only act on its own tenant — /tenant/{id}/... and
/billing/tenants/{id} where {id} is that key's tenant; any other path returns
403. Even there it can only read (the tenant, its quota and its billing
state), manage the tenant's own keys (list, mint, revoke) and use the
tenant portal routes (its own machines' state, figures, power actions,
password resets and consoles; its own networks and public addresses — see
The tenant portal under Multi-tenancy below). Changing the tenant, its quota
or its billing state — update, delete, quota changes, suspend, resume, limit,
unlimit — and creating or deleting machines, networks or volumes are reserved
for the operator and return 403 to a tenant key (see *Tenant-scoped API
keys* under Multi-tenancy below). The node API
token is never confined. The
WebSocket and gRPC transports accept the node API token only (not operator
or tenant-scoped keys). The local cenvero-str-ctl socket needs no token at all —
it is the node's always-available lifeline and can never be disabled.
3. Verify connectivity
Two endpoints need no token and are handy for a connectivity check. Examples on this page use these shell variables:
export NODE=https://<node-ip>:7070
export TOKEN=<your-api-token>
curl -k "$NODE/api/v1/health"
{
"status": "healthy",
"uptime": "3h14m22s"
}
This endpoint is deliberately minimal. It answers one question — is the agent
up, and for how long — and nothing more. Because it is reachable without a token,
anything it returned would be readable by anyone who can reach the port, so it
does not report the build version, the hardware, or any configuration. Point a
load balancer or an uptime monitor at it and treat a 200 as alive.
For the node's version and its network-acceleration detail, use the authenticated status endpoint:
curl -k "$NODE/api/v1/status" -H "Authorization: Bearer $TOKEN"
{
"status": "healthy",
"version": "1.0.0",
"uptime": "3h14m22s",
"acceleration": {
"mode": "software",
"summary": "Software (CPU)",
"detail": "Software (CPU) — hardware acceleration not available on this network card"
}
}
License
GET /api/v1/license — the node's license: who it was issued to, its plan and
channel, when it expires, the enforcement state, the plan's speed ceiling and the
capability map. Read-only — it never contacts the license server and never
changes anything, so it is safe to poll on a schedule.
curl -k "$NODE/api/v1/license" -H "Authorization: Bearer $TOKEN"
{
"installed": true,
"serial_number": "a3f9-...",
"plan": "enterprise",
"release_channel": "stable",
"valid_until": "2026-12-31T00:00:00Z",
"state": "active",
"days_remaining": 152,
"expired": false,
"mutations_allowed": true,
"hardware_grace": false,
"max_bandwidth_gbps": 25,
"features": { "bgp": true, "cluster": true, "ids": false }
}
| Field | Meaning |
|---|---|
state | active, warning (expiring soon), grace (just expired), frozen |
mutations_allowed | Whether state-changing requests are accepted right now |
hardware_grace | The license is valid but bound to hardware that no longer matches |
max_bandwidth_gbps | The plan's aggregate node ceiling; 0 means uncapped |
days_remaining | Negative once expired |
Branch on mutations_allowed, not on state. License enforcement never
severs traffic — a frozen node keeps forwarding packets and keeps its workloads
running; what it refuses is changes. So this is the field that tells automation
whether a write will be accepted.
With no license installed the answer is {"installed": false} with the identity
fields absent, rather than a document full of blanks that reads like a license.
GET /api/v1/docs (also unauthenticated) returns a short machine-readable index
of the endpoint paths — the same list published in this reference.
Because the node's certificate is privately managed, the curl examples below
use -k to skip system trust. To pin the certificate instead, fetch its
public key from the unauthenticated endpoint GET /api/v1/tls/pubkey (returns the
PEM as text/plain).
Conventions
- Base URL —
https://<node-ip>:7070; every REST path is under/api/v1. - HTTPS only — the agent refuses to serve plaintext; your client must trust (or pin) the node's certificate.
- JSON only — every request that carries a body must send
Content-Type: application/json; anything else is rejected with 415. Responses are always JSON. - Body cap — request bodies over 1 MiB are rejected with 413.
- Status codes — successful reads/updates return 200; resource creation returns 201.
- Timestamps — UTC throughout (RFC 3339, e.g.
2026-06-30T14:05:00Z), unless a field is explicitly a Unix epoch. - No pagination — list endpoints return the full collection under a named key (e.g.
{"networks": [ ... ]}); filters are provided per-endpoint via query parameters where noted. (The task list is the exception: it returns the newest 50 unless you ask for up to 500 withlimit.) - Compression — send
Accept-Encoding: gzipand JSON answers of 1 KiB or more come back compressed (Content-Encoding: gzip). The event stream is never compressed. - Tasks — an operation on a machine, an image or a volume answers with the id of the task that records it, in a
"task"field and aLocation: /api/v1/tasks/<id>header; the rest of the answer is unchanged.
Error responses
Errors are returned as JSON { "error": "..." } with a matching HTTP status:
| Status | Meaning |
|---|---|
400 | Malformed request — bad/invalid body or parameter (e.g. an invalid CIDR). |
401 | Missing or invalid bearer token: {"error":"unauthorized"}. |
403 | Forbidden — see the cases below. |
404 | Unknown resource (e.g. an unknown network or record id) — also one your credential may not see. |
413 | Request body over the 1 MiB cap. |
415 | Body sent without Content-Type: application/json. |
429 | Rate-limited, or too many failed auth attempts (temporary IP block). |
500 | The server could not complete the request. Unless the endpoint names its own answer, the error is the fixed sentence the server could not complete this request; the agent's log has the details, and what went wrong is written to the agent's log, not into the answer. |
501 | The operation is intentionally not supported (noted per-endpoint). |
503 | That subsystem is not enabled/wired on this node: {"error":"<name> service not available"}. |
A 403 is returned in any of these situations:
- Source not allowed — when an IP allowlist (
api_allowed_ips) is configured and your address is not on it:{"error":"forbidden: source address not allowed"}. In a cluster, each member applies its own list to your address, also when you reach it through another member; the member you called passes its refusal back unchanged (see Working with other members). - License frozen — a mutating call (POST/PUT/DELETE) while the license is frozen:
{"error":"license inactive: changes are frozen until the license is renewed; existing workloads keep running"}. Reads (GET) are never blocked, and running workloads are untouched. A tenant-scoped key gets the same refusal in its customer's terms:{"error":"changes are paused on this server right now; your machines keep running. Contact your provider if this lasts."}. In a cluster, removing a member, leaving and revoking a join code are never frozen (see Cluster). - Feature not in your plan — see plan-gated subsystems below.
- Tenant-scope violation — a tenant-scoped key used outside its own tenant:
{"error":"forbidden: a tenant key may only act on its own tenant"}. - Operator-only change — a tenant-scoped key asking to change its own tenant, quota or billing state:
{"error":"forbidden: this change is reserved for the operator; …"}. Send the call with the node API token, or an operator key or API token whose permissions allow it. - Missing permission — your account or token may see the object but not do this to it:
{"error":"you do not have permission to do this: it needs VM.PowerMgmt on /vms/vm-1a2b3c4d","missing_privilege":"VM.PowerMgmt","path":"/vms/vm-1a2b3c4d"}. An object it may not see answers 404, exactly as one that does not exist. - Password needed again — a change that gives someone more power or weakens a sign-in:
confirm your password to make this change(with"reauth_required": true) from the web console, andan API token cannot make this change; sign in to the web console to make itto an API token or operator key (see Access control).
Rate limits
The API applies a per-source-IP token-bucket limit. The defaults are
1000 requests per minute with a burst of 100; exceed it and you get
429 {"error":"rate limit exceeded"}. Tune them with api_rate_limit
(requests/minute) and api_rate_burst.
Plan-gated subsystems
Some subsystems are available only if your license plan includes them. For a plan-gated subsystem, every call — reads as well as writes — returns 403 with a message naming the missing feature (or "no license installed" when no license is active).
| Path prefix | Required feature |
|---|---|
/networks | Private Networks |
/dns/ | DNS |
/dhcp/ | DHCP |
/vxlan/ | VXLAN |
/lb, /lb/, /l7lb/ | Load Balancer |
/bgp/ | BGP |
/gateway/ | Gateway HA |
/bandwidth, /bandwidth/ | Bandwidth shaping (limits + pools + quotas) |
/cluster, /cluster/* | Cluster, except the five routes below |
Five cluster routes need no clustering in the plan, and also work while the
license is frozen: GET /cluster/status, GET /cluster/join-codes,
DELETE /cluster/join-codes/{id}, DELETE /cluster/members/{id} and
POST /cluster/leave. So a member whose plan lost clustering can still see
where it stands and be taken out (see Cluster).
Everything else — IPAM, firewall /rules, /routes, /vlan, /bridges,
/nics, /macbind, /forward, /bonds, /float, /flows, /accounting,
/tenant, /billing, /containers, and the operations endpoints — is available
on any active plan.
REST endpoint reference
Private networks
Managed private (SDN) networks. You create a network from a CIDR pool, and the agent automatically materializes one endpoint profile per usable host IP — each a fixed IP paired with a system-generated MAC. Attaching claims a free profile and programs its address binding into the data plane; detaching frees it. (Plan feature: Private Networks.)
Network fields
| Field | Type | Notes |
|---|---|---|
id | string | Server-assigned network id. |
name | string | Required on create, unique per node. |
cidr | string | Required, IPv4 only (e.g. 10.20.0.0/24). |
gateway | string | Optional gateway IP. |
vlan | int | Optional VLAN id to tag the network. |
tenant_id | string | Optional — scopes the network to one of your tenants. |
created_at | string | UTC timestamp. |
host_gateway | object | {"enabled", "snat", "dhcp"} — the host-gateway option (below). On create, pass "host_gateway": true and optionally "snat": true, "dhcp": true. |
Endpoint fields: id, network_id, ip, mac, state (free or
bound), and bound_at (set once bound).
List networks
GET /api/v1/networks
curl -k "$NODE/api/v1/networks" -H "Authorization: Bearer $TOKEN"
{
"networks": [
{
"id": "net-a1b2c3d4",
"name": "app-net",
"cidr": "10.20.0.0/24",
"gateway": "10.20.0.1",
"vlan": 100,
"tenant_id": "t-acme",
"created_at": "2026-06-30T12:00:00Z"
}
]
}
Create a network
POST /api/v1/networks — body: name and cidr required; gateway, vlan,
tenant_id optional. Returns 201. A cidr sharing any address with another
network on the node — whoever owns it — answers 400
(… shares addresses with another network on this node; choose another range),
naming nothing but the range asked for.
curl -k -X POST "$NODE/api/v1/networks" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name":"app-net","cidr":"10.20.0.0/24","gateway":"10.20.0.1","vlan":100}'
{
"status": "created",
"network": {
"id": "net-a1b2c3d4",
"name": "app-net",
"cidr": "10.20.0.0/24",
"gateway": "10.20.0.1",
"vlan": 100,
"created_at": "2026-06-30T12:00:00Z"
}
}
With "host_gateway": true (a gateway is then required) the node holds the
network's gateway address on the workload bridge; "snat": true also lets the
network reach the internet through the node's public address and "dhcp": true
serves it over DHCP (both imply the host gateway). A setting that cannot be
applied — snat on a node with no uplink configured, for instance — is refused
with 400 and nothing is created.
curl -k -X POST "$NODE/api/v1/networks" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name":"web","cidr":"10.60.0.0/24","gateway":"10.60.0.1","host_gateway":true,"snat":true}'
Set or remove a network's host gateway
PUT /api/v1/networks/{id}/host-gateway — body {"snat":bool,"dhcp":bool}
(an empty body is the gateway alone). The body is the whole setting: what it no
longer asks for is removed. DELETE turns the option off, removing everything it
added. Both return the network; 404 for an unknown network.
curl -k -X PUT "$NODE/api/v1/networks/net-a1b2c3d4/host-gateway" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"snat":true}'
curl -k -X DELETE "$NODE/api/v1/networks/net-a1b2c3d4/host-gateway" -H "Authorization: Bearer $TOKEN"
{ "status": "updated", "network": { "id": "net-a1b2c3d4", "host_gateway": { "enabled": true, "snat": true, "dhcp": false } } }
Get a network
GET /api/v1/networks/{id}
curl -k "$NODE/api/v1/networks/net-a1b2c3d4" -H "Authorization: Bearer $TOKEN"
{ "network": { "id": "net-a1b2c3d4", "name": "app-net", "cidr": "10.20.0.0/24", "gateway": "10.20.0.1" } }
Delete a network
DELETE /api/v1/networks/{id}
curl -k -X DELETE "$NODE/api/v1/networks/net-a1b2c3d4" -H "Authorization: Bearer $TOKEN"
{ "status": "deleted", "id": "net-a1b2c3d4" }
List a network's endpoints
GET /api/v1/networks/{id}/endpoints
curl -k "$NODE/api/v1/networks/net-a1b2c3d4/endpoints" -H "Authorization: Bearer $TOKEN"
{
"endpoints": [
{ "id": "ep-1111", "network_id": "net-a1b2c3d4", "ip": "10.20.0.2", "mac": "02:ce:0a:14:00:02", "state": "bound", "bound_at": "2026-06-30T12:05:00Z" },
{ "id": "ep-2222", "network_id": "net-a1b2c3d4", "ip": "10.20.0.3", "mac": "02:ce:0a:14:00:03", "state": "free" }
]
}
There is one endpoint for every usable address except the gateway, which is
reserved and never listed. Unless you supply one, an endpoint's MAC is derived
from its IP: 02:ce: followed by the four octets of the address in hex.
Add ?mac=52:54:00:ab:01:02 to narrow the listing to a single address. This is
the efficient way to answer "which endpoint is this workload on" when
reconciling — a /24 otherwise returns 253 rows. Matching ignores case, and an
address that is not present returns an empty list rather than an error.
curl -k "$NODE/api/v1/networks/net-a1b2c3d4/endpoints?mac=52:54:00:ab:01:02" \
-H "Authorization: Bearer $TOKEN"
Attach an endpoint
POST /api/v1/networks/{id}/attach — claims an endpoint and binds it. Body is
optional: send {"ip":"10.20.0.2"} to claim a specific address, or an empty body
to take the next free one. Idempotent — attaching an already-bound IP returns that
same endpoint. Returns 200.
Add "mac" to give the endpoint a specific hardware address instead of the one
it was assigned. Use this when the workload already has a fixed address of its
own — a virtual machine image, or an appliance whose license is tied to one — so
the fabric accepts the address it will actually send from.
curl -k -X POST "$NODE/api/v1/networks/net-a1b2c3d4/attach" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"ip":"10.20.0.2"}'
# ...or claiming that address for a workload that already has this MAC
curl -k -X POST "$NODE/api/v1/networks/net-a1b2c3d4/attach" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"ip":"10.20.0.2","mac":"52:54:00:ab:01:02"}'
{
"status": "attached",
"endpoint": { "id": "ep-1111", "network_id": "net-a1b2c3d4", "ip": "10.20.0.2", "mac": "02:ce:0a:14:00:02", "state": "bound", "bound_at": "2026-06-30T12:05:00Z" }
}
Change an endpoint's MAC address
PUT /api/v1/networks/{id}/endpoints/{eid}/mac — replaces the endpoint's
hardware address, keeping its IP. Returns 200.
On a bound endpoint the anti-spoof binding moves to the new address as part of the change, so the workload is never left able to send from an address the fabric would reject. Setting the address it already has succeeds and changes nothing.
curl -k -X PUT "$NODE/api/v1/networks/net-a1b2c3d4/endpoints/ep-1111/mac" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"mac":"52:54:00:ab:01:02"}'
{
"status": "updated",
"endpoint": { "id": "ep-1111", "network_id": "net-a1b2c3d4", "ip": "10.20.0.2", "mac": "52:54:00:ab:01:02", "state": "bound", "bound_at": "2026-06-30T12:05:00Z" }
}
400 is returned for an address that is not a MAC, for a multicast address (one can never be a source address, so traffic from it would be dropped), and for an address already held by another endpoint — the response names the endpoint holding it, since two endpoints sharing an address would collide in the anti-spoof binding.
Detach an endpoint
POST /api/v1/networks/{id}/endpoints/{eid}/detach — frees the endpoint and
releases its binding.
curl -k -X POST "$NODE/api/v1/networks/net-a1b2c3d4/endpoints/ep-1111/detach" \
-H "Authorization: Bearer $TOKEN"
{
"status": "detached",
"endpoint": { "id": "ep-1111", "network_id": "net-a1b2c3d4", "ip": "10.20.0.2", "mac": "52:54:00:ab:01:02", "state": "free" }
}
Routed public addresses
The public IPv4 addresses your provider routes to this server, handed to virtual machines one at a time. See Public Addresses for the model. (Plan feature: Private Networks.)
List routed addresses
GET /api/v1/routed-addresses — optional ?tenant_id= narrows the list to what
one tenant may use and uses.
{
"gateway": "169.254.1.1",
"ranges": [ { "id": "rr-4f0c2a91d3e7", "cidr": "203.0.113.16/29", "tenant_id": "", "size": 8, "used": 1, "free": 7 } ],
"addresses": [ { "ip": "203.0.113.16", "range_id": "rr-4f0c2a91d3e7", "tenant_id": "t-acme", "used_by": "vm-3f9a1c2e", "mac": "02:ce:cb:00:71:10" } ]
}
Add routed addresses
POST /api/v1/routed-addresses — body {"cidr": "203.0.113.16/29"} (or one
address), optional tenant_id to reserve it for one tenant and description.
Returns 201; 400 for a private, reserved or too-wide block; 409 when
it overlaps a block you already added or one of your networks, or holds an
address of the server itself.
Remove routed addresses
DELETE /api/v1/routed-addresses/{id or prefix} — the prefix with its slash
escaped (203.0.113.16%2F29) or written as a dash (203.0.113.16-29); ?cidr=
works too. 409 while a virtual machine uses one of its addresses.
A virtual machine takes an address with "public_ip": "auto" (or a specific
address) on one of the entries in its networks list at POST /api/v1/vms. The same
request names the storage pool the machine's disk and seed image are kept in with "pool" (the
ID of a pool, see Storage pools below); leave it out for the default pool.
A create answers 201 with the machine when it finishes within 20 seconds. A
longer create answers 202 with the machine's id and its task, and the
create carries on: follow the task at GET /api/v1/tasks/{id} until it ends
succeeded or failed. Do not send the create again while its task runs.
Disc images and machine settings
The disc library, a machine's CD-ROM drives, its options and its first-boot settings. A machine is created, started and deleted under Compute. The rules are on Installation discs, Creating virtual machines and Firmware, resizing, interfaces and the guest agent. These routes are operator-only: a tenant-scoped key cannot reach them. A change needs a licence that includes Compute and is not frozen. A read never needs either.
Disc library
GET /api/v1/isos lists the discs the caller may see: 200 with {"isos": [...]}.
GET /api/v1/isos/{id} shows one disc and the machines you may see that hold it (attached_to):
200, or 404 when there is none.
POST /api/v1/isos takes {"name", "url", "sha256"}. The download is checked
against the SHA-256 and the ISO 9660 structure in the background, and the answer is
202 with the disc and its task. A path is refused: a file is registered
from the node's own command line.
curl -k -X POST "$NODE/api/v1/isos" -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"debian-13-netinst","url":"https://downloads.example.net/debian-13-netinst.iso","sha256":"<hex>"}'
DELETE /api/v1/isos/{id} removes a disc that no machine holds (200). While a
machine holds it, the answer is 409 with the machines in machines: eject the
disc from them first. A disc still being brought in cannot be deleted either.
Reading needs Image.Audit. Registering and deleting need Image.Allocate.
CD-ROM drives
GET /api/v1/vms/{id}/cdroms lists a machine's drives: {"cdroms": [...]}. A
drive is 0 (the install disc) or 1 (the driver disc).
PUT /api/v1/vms/{id}/cdroms/{slot} takes {"iso_id": "iso-7d4e2f10"}. An empty
iso_id ejects the disc. The answer is 200 with "live": true when the
running machine took the change, and 202 with "live": false when the change
applies at the next start.
DELETE /api/v1/vms/{id}/cdroms/{slot} ejects the disc and removes the drive
(200). Reading needs VM.Audit. Changing a drive needs VM.Config.Disk.
Machine options
GET /api/v1/vms/{id}/options returns the machine's name, protected,
boot_order (empty for the default order), effective_boot_order,
start_at_boot, and its firmware with firmware_editable, which is always
false.
PUT /api/v1/vms/{id}/options takes {"name", "protected", "boot_order", "start_at_boot",
"anti_affinity"}, and each may be left out. anti_affinity names the machine's
anti-affinity group, and an empty string clears it. A group needs a machine of a
tenant and every member running a version that supports it; otherwise the answer is 409 with the sentence for
the reason, and a group in the wrong form is 400 (see
Placing machines). boot_order names disk, cdrom0 and cdrom1, each at
most once. The answer is 200 with the options. It is 409 for a name another
machine of the tenant has, and 400 for a firmware field, which is refused with
"firmware is chosen when a machine is created; it cannot be changed afterwards".
Changing options needs VM.Config.Options.
First-boot settings
GET /api/v1/vms/{id}/cloud-init returns the hostname, the DNS servers, each SSH
key's type and fingerprint, the user-data's size, and the settings' revision: an id
that changes at every edit, and null before the first. It never returns a key or
the user-data text, nor anything derived from the text.
PUT /api/v1/vms/{id}/cloud-init takes {"hostname", "dns", "ssh_keys", "user_data", "apply_again"},
and each may be left out. A list replaces the one on the machine, and apply_again
makes the next start a new first boot for the guest. The answer is 200. It is
409 for a machine installed from a disc, which has no first-boot settings, and
400 for user-data over 64 KiB. Changing them needs VM.Config.CloudInit.
Disks, snapshots and backups
A machine's disks, the snapshots and backups of its boot disk, and the backup schedule of each volume. The rules are on Snapshots, backups and schedules. These routes are operator-only: a tenant-scoped key cannot reach them. A change needs a licence that includes Storage (a Compute licence includes it) and is not frozen. A read never needs either.
A machine's disks
GET /api/v1/vms/{id}/disks returns {"disks": [...]}: the boot disk first, then
the volumes attached to the machine, in target order. Each disk has volume_id,
role (boot or data), target, size_bytes, pool, state, snapshots (how
many it has), backups (how many complete backups it has) and schedule. The
schedule is the disk's backup schedule in the shape the volume's schedule route
below answers, or null when the disk has no schedule. Reading needs VM.Audit.
Snapshots of the boot disk
GET /api/v1/vms/{id}/snapshots returns {"snapshots": [...]}. Each snapshot has
id, volume_id, name, state, consistency (quiesced, crash-consistent or
offline), created_at, and reason when it has one.
POST /api/v1/vms/{id}/snapshots takes {"name", "quiesce"}, and both may be left
out. quiesce defaults to true: the guest's file systems are frozen when its agent
answers. The answer is 202 with "status": "created", the snapshot and its
task. A machine whose boot disk is not recorded yet answers 409 with "this
machine's boot disk is being recorded; try again in a moment". Taking a snapshot
needs VM.Snapshot.
Going back to a snapshot and deleting one are Storage's routes. Going back needs the
machine stopped first: POST /api/v1/snapshots/{id}/revert answers 200 with
"status": "reverted" and the volume. DELETE /api/v1/snapshots/{id} merges the
snapshot back into the disk, and no data is lost.
Backups of the boot disk
GET /api/v1/vms/{id}/backups returns {"backups": [...]}. Each backup has id,
volume_id, volume_name, tenant_id, kind (full or incremental),
consistency, state, size_bytes, file_bytes, created_at, completed_at
and schedule_id, which is "" for a backup taken by hand. parent_id and error
appear when they are set.
POST /api/v1/vms/{id}/backups takes {"kind", "keep", "target"}. kind is full,
incremental, or left empty for an automatic backup, which is incremental when one
can be taken. keep sets how many backups taken by hand the disk keeps, and 0 keeps
every one; a schedule's own keep is not changed by it. The answer is 202 with
"status": "started",
the backup and its task. An incremental backup needs a running machine: a stopped
machine is always backed up in full. A boot disk on a block pool takes only full backups:
an incremental one is refused with 409 ("an incremental backup is not available on a
thin-provisioned or ZFS pool yet: take a full backup, or keep the volume on a directory
pool"). Taking a backup needs VM.Backup.
target is optional. It names a backup target that the
backup is copied to once it is checked. The backup then shows target_id, target_state
(uploading, complete, failed or removing; empty when no copy is set) and, after a
failed copy, target_error. Once a copy is kept on its target, target_check_state is
check_failed when its last check failed and empty otherwise, target_checked_at is when it was
last checked (null before its first check), and target_check_error is the sentence of a failed check. A target the node does not have is refused with 400.
Restoring a backup
POST /api/v1/volume-backups/{id}/restore takes {"name", "pool"} to restore into a new
volume, the default, or {"in_place": true, "discard_snapshots"} to replace the
disk's contents. The body is decoded strictly. A restore into a new volume answers
202 with "status": "restoring", the volume and its task. An in-place restore
is refused with 409 unless the machine is stopped (or the volume is detached),
the backup fits the disk, and the disk's snapshots are either absent or discarded
with "discard_snapshots": true. On a block pool the backup must be exactly the size of the
disk: a backup of another size is refused with 409. A released boot disk can only be restored into a
new volume. "pool" names the storage pool the new volume is kept in (see Storage pools
below); leave it out for the default pool. An in-place restore keeps the volume's own
pool and takes no "pool". GET /api/v1/volume-backups lists the node's backups.
Restoring needs Storage.Backup.
Storage pools
GET /api/v1/storage/pools returns 200 with {"pools": [...], "backends": [...]}. pools
holds the default pool and each other pool, with its id, name, backend, location (the
name of a directory pool's directory, empty for a block pool), state (ready or
unreadable), size_bytes, used_bytes, free_bytes and volumes. The backends list the
kinds of pool, and each backend is {"name", "available"}: dir is always available, and
thin-provisioned and zfs are available where this node has their tools (see
Storage pools). On a node in a cluster the answer also carries
cluster_level and placement_ready: the cluster's level, and whether it is ready for a shared
declaration (level 5, with every member on a version that supports it). A node in no cluster has
no cluster_level. Each pool also says shared (whether this node has declared it shared) and
sharable (whether its directory is on a filesystem that can be shared between members, which a
declaration needs; a block pool is never sharable). Both are read each time the list is read. A pool
that is not sharable also says why, in sharable_refusal: pool.shared_fs (its directory is on an
ordinary filesystem), pool.shared_check (the node could not check its directory) or pool.shared_kind
(a block pool). The sharable_refusal field is absent from a sharable pool.
GET /api/v1/storage/pools/{id} returns 200 with {"pool": {...}}.
POST /api/v1/storage/pools takes {"name", "backend", "location"}. backend is "dir",
"thin-provisioned" or "zfs". For "dir", location (optional) names the directory on
disk. For "thin-provisioned" and "zfs", location is required: group/pool for a
thin-provisioned pool, and pool or pool/dataset for ZFS. It answers 202 with
"status": "created", the pool and its task. A kind this node has no tools for is refused
with 501 ("this kind of pool is not available on this node"). A name that does not follow
the rules, or a location in the wrong form, is refused with 400 ("a thin-provisioned pool's
location is its group and pool name, written as group/pool; a ZFS pool's location is its pool
name, or pool/dataset"). A location the host does not have is also 400, with "the storage
location of this pool does not exist on this node: check its name, or create it first". A name
another pool has, a location another pool uses, a location that is not healthy, or a
directory that is not empty is refused with 409.
DELETE /api/v1/storage/pools/{id} answers 200 with "status": "deleted" and its
task. A pool that still holds volumes is refused with 409, and the default pool
cannot be deleted. Reading a pool needs Storage.Audit; creating or deleting one needs
Storage.Allocate.
PUT /api/v1/storage/pools/{id}/shared takes {"shared": true} to declare a directory pool shared between the members, or {"shared": false} to take the declaration back, and answers 200 with the pool as it now stands. A body that is neither is refused with 400, and so is a pool the node will not share (a thin-provisioned or ZFS pool, or a directory on a filesystem that cannot be shared), with the reason the node gives. A declaration needs every member of the cluster to run a version that supports sharing, and until then, and on a node in no cluster, it answers 409 with the cluster's sentence. A take-back works at any level, outside a cluster and under a licence freeze; it is refused with 409 only while a machine is moving live on this member, and with 503 when the node cannot tell. Both need Storage.Allocate on the pool and a licence that includes Storage. See Shared storage pools.
Volume backup schedules
GET /api/v1/volumes/{id}/backup-schedule returns 200 with {"schedule": {...}},
or 404 when the volume has none.
PUT /api/v1/volumes/{id}/backup-schedule takes {"expression", "kind", "keep",
"enabled", "target"}. expression is daily@HH:MM, weekly@DAY-HH:MM or every-Nh, with
UTC times. kind is full or incremental. keep is 1 to 1000, and enabled
defaults to true. target is optional: it names the backup target
that each backup the schedule takes is copied to, and it may be left out. A target the
node does not have is refused with 400. The answer is 200 with
{"status": "set", "schedule": {...}}.
A refused expression, kind or keep is 400, with the node's sentence for it. On a volume on a block pool, kind must be full: an incremental schedule is refused with 409. A
volume that is being deleted, a released boot disk, and a node that already has 256
schedules are 409.
DELETE /api/v1/volumes/{id}/backup-schedule removes the schedule: 200 with
{"status": "removed", "volume_id"}. The backups it made stay.
POST /api/v1/volumes/{id}/backup-schedule/run starts a run now: 202 with
{"status": "started", "schedule"} and its task. A run requested while a backup of
the volume is going waits for it.
GET /api/v1/backup-schedules lists the schedules of the volumes you can see: 200
with {"schedules": [...]}.
A schedule has id (sch- and eight hexadecimal digits, which the backups it made
carry as schedule_id), volume_id, expression, kind, keep, enabled,
next_run, last_run, last_result (ok, failed, busy, skipped, or null
before the first run), last_error, timezone (always UTC) and target, the id of
the backup target it copies to, or "" when it has none. Reading a schedule needs
Storage.Audit. Setting, removing and running one needs Storage.Backup.
curl -k -X PUT "$NODE/api/v1/volumes/vol-7d4e2f10/backup-schedule" -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"expression":"daily@02:30","kind":"incremental","keep":7}'
Backup targets
A backup target is a bucket on an S3-compatible service, where the node keeps an
encrypted copy of each backup that names it. The rules are on
Off-site copies. These routes are operator-only:
a tenant-scoped key cannot reach them. Reading needs Storage.Audit. Creating, changing,
deleting, testing, and exporting or importing a key need Storage.Allocate. Restoring a copy
needs Storage.Backup on the target and Storage.Allocate on the volumes. A change or a
restore needs a licence that includes Storage and is not frozen.
A target has id (tgt- and eight hexadecimal digits), name, endpoint, region,
bucket, prefix, path_style, key_hint (… and the last four characters of the key
id), secret (set or not set), last_test ({"at", "result"}, or null before a
test) and created_at. A credential is never returned. An id the caller may not see
answers exactly as an id that does not exist: 404.
GET /api/v1/storage/targets returns 200 with {"targets": [...]}, the oldest first.
POST /api/v1/storage/targets takes {"name", "endpoint", "bucket", "access_key_id",
"secret_access_key"}. "region" defaults to us-east-1, and "prefix" defaults to
cenvero-stratum/. "path_style" defaults to false. endpoint starts with https://.
The answer is 200 with "status": "created" and the target. The body is decoded
strictly, so an unknown field is 400. A name another target has is 409, and an
address, bucket, region or prefix the node cannot use is 400 with the node's sentence
for it. Creating a target does not contact the service.
GET /api/v1/storage/targets/{id} returns 200 with {"target": {...}}.
PUT /api/v1/storage/targets/{id} changes any of the fields of the create. The access key
id and the secret access key are given together or not at all. The answer is 200 with
"status": "updated" and the target. A change of endpoint is audited with the old and the
new host, never with a credential.
DELETE /api/v1/storage/targets/{id} answers 200 with "status": "deleted" and the
target's id. It is refused with 409 while a schedule or a backup names the target.
POST /api/v1/storage/targets/{id}/test writes a small test file under the target's
prefix, reads it back and removes it. It answers 200 with "status": "ok" and the
target, whose last_test is updated. A refused credential is 409 with "the backup
target refused the credentials". A target that cannot be reached is 409 with "the
backup target could not be reached; check its address and credentials".
POST /api/v1/storage/targets/{id}/key-export answers 200 with "status": "exported",
the target's id, "key" (base64) and a "note". It needs sudo: a web-console session that
confirmed its password in the last five minutes, or the node's own API token. A console
session that has not confirmed gets 403 with "reauth_required": true. Any other token
gets 403 with "an API token cannot make this change; sign in to the web console to
make it". Each export is audited, and the key is in no log, task or audit record. A key is
never sent to another node: the command line runs this route only on the node that holds
the target.
POST /api/v1/storage/targets/{id}/key-import takes {"key": "<the key the export printed>"}
and sets the target's key from it. It has the same sudo gate as the export, with the same
refusals. The answer is 200 with "status": "imported" and the target, which never carries
the key. A key that is not base64, or not the right length, is 400 with "that is not a
backup target's key: paste the whole key that the key export printed". A different key is
409 with "this target already has its own key, and copies made with it are kept here: the
key cannot be replaced while they are" while the node can read the target's key and holds copies
on the target. Importing the key the target already has changes nothing.
GET /api/v1/storage/targets/{id}/copies returns 200 with {"copies": [...], "truncated": false}, one entry for
each copy the target holds, read from the copies on the target. Each entry has id,
volume_name, size_bytes, kind (full or incremental), chain_id (the full copy at the
start of its set, which is the copy itself for a full copy), parent_id (the copy it builds on,
empty for a full copy), created_at, source_node (the id of the node that made it), state and
reason. The state is restorable, incomplete, unreadable or refused. The reason is empty
for a restorable copy, and the node's sentence for any other. truncated is true when the listing
stopped early: a target that holds more than 2,000 records is listed in part, and then some of its
copies are not shown. For a copy this node made, check_state, checked_at and check_error give the
node's last check of it (see the check route below). Reading needs Storage.Audit. A
target whose credentials or key cannot be read on this node, or that cannot be reached, answers
503 with the node's sentence.
POST /api/v1/storage/targets/{id}/copies/{copy}/restore restores a copy into a new volume on this
node, as a task. It takes {"name", "pool"}, and both may be left out. The answer is 202 with
"status": "restoring", the new volume and the task. The copies the copy builds on are fetched and
checked before the new volume is written. It needs Storage.Backup on the target and Storage.Allocate
on the volumes, and a licence that includes Storage and is not frozen. A copy the target does not
hold is 404. A copy that cannot be restored is 409 with the node's sentence for it. A name
the node cannot use, or a pool it does not have, is 400.
POST /api/v1/storage/targets/{id}/copies/{copy}/check checks one copy the target holds, now, and records
the result on this node. It takes no body. The answer is 200 with "status", which is passed or
failed; copy and target; check_state (check_failed or empty); checked_at; and, for a failed check,
check_error, the sentence of what was wrong. A copy with no complete copy on that target is 404, and a
copy being sent or checked is 409. A target that cannot be reached, or that refuses the credentials,
cannot judge the copy: the answer is 503 with the node's sentence, and nothing is recorded. It needs
Storage.Audit on the target, the privilege the copies listing needs. It is a read under the licence rules,
so a frozen licence does not refuse it, and it is audited with its result.
curl -k -X POST "$NODE/api/v1/storage/targets" -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" --data-binary @offsite-target.json
curl -k -X POST "$NODE/api/v1/storage/targets/tgt-3b8e0a71/test" -H "Authorization: Bearer $TOKEN"
Keep the file that holds the body readable only by the operator: it contains the secret.
Templates, clones and the image catalogue
A template is a copy of a stopped machine's boot disk. A clone is a new machine made from a template or from a stopped machine. The rules are on Templates and clones and The image catalogue. These routes are operator-only. A change needs a licence that includes Compute and is not frozen.
Templates and clones
POST /api/v1/vms/{id}/templates takes {"name", "shared"}, and shared may be left
out. The answer is 202 with {"image": {...}} and its task. The image is a
template: its kind is template, with source_vm, source_tenant, shared,
sha256, size_bytes, and a state of making, ready or failed. A running
machine answers 409: "this machine is running; stop it first". Needs
Image.Allocate and VM.Audit on the machine.
PUT /api/v1/images/{id} takes {"shared": true} or {"shared": false}, and answers
200 with {"image": {...}}. It works on templates only. Changing sharing needs
Image.Allocate, and the change is recorded as the event compute.template_shared,
which names the image, its name and the new value.
POST /api/v1/vms/{id}/clone takes {"name", "networks", "hostname", "tenant_id", "pool"}.
Each entry in networks is {"network_id"}, with an "ip" when you want one.
hostname defaults to the clone's name, and tenant_id to the source's tenant. pool names the pool the clone's boot disk is kept on (see Storage pools), and the default pool is used when it is left out. The
answer is 202 with {"vm": {...}} and its task. A running source answers
409 with "this machine cannot be cloned while it runs: stop it first", and a
suspended tenant answers 409 with "this tenant is suspended: its machines cannot
start, be cloned or be made into templates". Needs VM.Allocate on the machine.
The image catalogue
GET /api/v1/images/catalogue answers 200 with {"catalogue": [...]}. Each entry
has id, name, distribution, release, arch, format, url, sha256,
size_bytes, firmware, cloud_init, default_user, checksum_source (the
publisher's checksum file) and checked, the date it was checked. Reading needs
Image.Audit.
POST /api/v1/images takes {"name", "catalogue"} to install an entry. The answer is
202 with the image and its task, and the download is checked against the
entry's SHA-256. Give exactly one source: a catalogue id, or a url with its
sha256. An id the catalogue does not have is 404 with "the catalogue has no
image with that id".
IP address management (IPAM)
Address pools and the individual IP allocations drawn from them. Creating a private network registers a matching pool automatically; you can also manage pools directly.
Pool fields: id, name (required), subnet (required CIDR),
gateway, range_start, range_end, is_ipv6, and an optional tenant_id.
List pools
GET /api/v1/ipam/pools — optional ?tenant_id= filter.
curl -k "$NODE/api/v1/ipam/pools" -H "Authorization: Bearer $TOKEN"
{
"pools": [
{ "id": 1, "name": "app-net", "tenant_id": "t-acme", "subnet": "10.20.0.0/24", "gateway": "10.20.0.1", "range_start": "10.20.0.2", "range_end": "10.20.0.254", "is_ipv6": false }
]
}
Create a pool
POST /api/v1/ipam/pools — name and subnet required; gateway,
range_start, range_end, is_ipv6, tenant_id optional. Returns 201.
- A missing
range_startorrange_enddefaults to the first or last host address of the subnet. - The range must lie inside the subnet and run forwards (start at or before end); otherwise 400.
gateway,range_startandrange_endmust be IP addresses when given — a malformed one is 400, not silently ignored.- A pool whose subnet or range overlaps another pool of the same tenant is refused with 400. Different tenants may reuse the same private range.
- The gateway is never handed out by
allocate, even when it sits inside the range.
curl -k -X POST "$NODE/api/v1/ipam/pools" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name":"edge","subnet":"10.40.0.0/24","gateway":"10.40.0.1","range_start":"10.40.0.10","range_end":"10.40.0.200"}'
{
"status": "created",
"pool": { "id": 2, "name": "edge", "subnet": "10.40.0.0/24", "gateway": "10.40.0.1", "range_start": "10.40.0.10", "range_end": "10.40.0.200", "is_ipv6": false }
}
List allocations
GET /api/v1/ipam/allocations — every allocation across all pools; optional
?tenant_id= filter.
curl -k "$NODE/api/v1/ipam/allocations" -H "Authorization: Bearer $TOKEN"
{ "allocations": [ { "id": 10, "pool_id": 1, "ip": "10.20.0.5", "hostname": "web-1" } ] }
Allocate an IP
POST /api/v1/ipam/allocate — body: pool_id (required), hostname
(optional). Returns the assigned address.
curl -k -X POST "$NODE/api/v1/ipam/allocate" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"pool_id":1,"hostname":"web-2"}'
{ "status": "allocated", "id": 11, "pool_id": 1, "ip": "10.20.0.6", "hostname": "web-2" }
Release an IP
POST /api/v1/ipam/release — body: pool_id and ip (both required).
curl -k -X POST "$NODE/api/v1/ipam/release" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"pool_id":1,"ip":"10.20.0.6"}'
{ "status": "released" }
On a cluster the answer can also be a refusal, and nothing is changed by it:
- 409 when an endpoint on another server of the cluster holds the address, with the error "This address is held by an endpoint on another server of the cluster, so it cannot be released here. Nothing was changed. It is released when that endpoint is removed."
- 503 when the cluster's record of the address cannot be read yet, with the error "The cluster's record of this address could not be read, so it was not released. Nothing was changed. Try again."
Delete a pool
DELETE /api/v1/ipam/pools/{id} — removes the pool and every allocation in it.
Addresses handed out from the pool stop being reserved, so do this only once
nothing is using them.
curl -k -X DELETE "$NODE/api/v1/ipam/pools/1" -H "Authorization: Bearer $TOKEN"
{ "status": "deleted", "id": 1 }
Deleting a pool that does not exist returns 404.
Bridges
The node's software bridges and their member ports. A node ships with two managed
bridges — cnv-mgmt-br0 (management) and cnv-user-br0 (tenant/user traffic) —
and you can create and wire additional ones.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/bridges | List bridges and their member interfaces |
| POST | /api/v1/bridges | Create a bridge (name required) |
| DELETE | /api/v1/bridges/{name} | Delete a bridge |
| POST | /api/v1/bridges/{name}/ports | Attach an interface (interface required) |
| DELETE | /api/v1/bridges/{name}/ports/{iface} | Detach an interface |
curl -k "$NODE/api/v1/bridges" -H "Authorization: Bearer $TOKEN"
{ "bridges": [ { "name": "cnv-user-br0", "interfaces": ["cnv-nic-1"] } ] }
# Create a bridge and attach a NIC
curl -k -X POST "$NODE/api/v1/bridges" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name":"cnv-svc-br0"}'
curl -k -X POST "$NODE/api/v1/bridges/cnv-svc-br0/ports" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"interface":"cnv-nic-2"}'
{ "status": "added", "bridge": "cnv-svc-br0", "interface": "cnv-nic-2" }
Detach a port → DELETE /api/v1/bridges/cnv-svc-br0/ports/cnv-nic-2 returns
{ "status": "removed", "bridge": "cnv-svc-br0", "interface": "cnv-nic-2" }.
Delete a bridge → { "status": "deleted", "name": "cnv-svc-br0" }.
Each change is all or nothing: one the server refuses leaves nothing behind. These are refused, with a sentence that says why and that nothing was changed:
- deleting
cnv-mgmt-br0orcnv-user-br0, or adding or removing their ports here (409); - a new bridge with the name of an interface the server already has (409);
- as a port, an interface that carries the way the server is reached — the management bridge and its card, the configured uplink, the device a default route leaves through, the device holding the API's or the cluster's address, and their ports (409);
- as a port, an interface with addresses of its own, one already part of a bridge or a bond (409), or one the server does not have (404);
- deleting a bridge that carries the way the server is reached or its workloads' way out — it is the configured uplink or LAN interface, a default route leaves through it, it holds the API's or the cluster's address, or it is a port of the management bridge — or taking a port out of it while that port has a link (409). A port that has no link, or is gone, can be taken out, so a failed card can be replaced.
Network interfaces (NICs)
Read-only inventory of the node's physical interfaces, including the uplinks the
installer renamed to cnv-nic-* (for those, original_name is empty). Renaming is
a privileged boot-time operation and is not exposed over the API.
GET /api/v1/nics — pass ?refresh=1 to re-scan hardware before returning.
curl -k "$NODE/api/v1/nics" -H "Authorization: Bearer $TOKEN"
{
"nics": [
{ "original_name": "", "stratum_name": "cnv-nic-0", "pci": "0000:01:00.0", "driver": "ixgbe", "speed_mbps": 10000, "status": "up" }
]
}
MAC bindings
Let a MAC address through the workload bridge's anti-spoofing guard, which drops frames from MAC addresses it has no binding for. Managed-network endpoints get their bindings automatically; use these endpoints to manage bindings for addresses you bridge in from outside.
A binding takes only the MAC address (a unicast address of six bytes): the bridge
lets that address through on every port and VLAN. port_id, vlan_id and the
soft mode are refused with 400, and a binding saved with one before lists it
under not_enforced. A MAC that is already bound is 409. The binding of a
running workload — an attached endpoint, or a routed address a machine holds —
cannot be removed (409, naming what holds it): detach the workload instead.
Each change is all or nothing.
Each binding names its owner by kind in owner_kind: operator for a binding
added here, endpoint for an address of a managed network, or routed for a
routed public address. Only an operator binding is removed here (409 for any
other kind): an endpoint or routed binding goes with its address, and the
server removes a stored one that its address no longer holds.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/macbind | List bindings |
| POST | /api/v1/macbind | Create a binding (mac required) |
| DELETE | /api/v1/macbind/{mac} | Remove a binding by MAC |
curl -k -X POST "$NODE/api/v1/macbind" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"mac":"02:1a:4f:14:00:09"}'
{ "status": "created", "binding": { "id": 4, "mac": "02:1a:4f:14:00:09", "port_id": 0, "vlan_id": 0, "mode": "hard", "owner_kind": "operator" } }
Remove → DELETE /api/v1/macbind/02:1a:4f:14:00:09 returns
{ "status": "deleted", "mac": "02:1a:4f:14:00:09" }.
DHCP leases
Read the live DHCP lease table. (Plan feature: DHCP.)
GET /api/v1/dhcp/leases — optional ?state= filter, one of active,
expired, revoked. expires_at is a Unix UTC timestamp.
curl -k "$NODE/api/v1/dhcp/leases?state=active" -H "Authorization: Bearer $TOKEN"
{
"leases": [
{ "id": 3, "mac": "52:54:00:de:ad:01", "ip": "10.30.0.10", "state": "active", "hostname": "db-primary", "expires_at": 1782825600 }
]
}
Static reservations and early releases are managed from the CLI (cenvero-str-ctl dhcp reserve/dhcp release).
DNS
The authoritative DNS manager: managed zones and their records, plus DNSSEC material. (Plan feature: DNS.)
Record fields: id, zone_id, name, type (A, AAAA, CNAME, TXT,
NS, PTR — the types the server answers; any other is 400), value (one of
its type: an IPv4 address for A, an IPv6 address for AAAA, a domain name for
CNAME, NS and PTR, 1 to 255 characters for TXT), ttl (defaults to 300
when omitted), and an optional source_subnet for split-horizon answers, which
must be a network.
List zones
GET /api/v1/dns/zones
curl -k "$NODE/api/v1/dns/zones" -H "Authorization: Bearer $TOKEN"
{ "zones": [ { "id": 1, "name": "app-net.internal.", "soa": "ns.app-net.internal.", "serial": 2026063001 } ] }
Create a zone
POST /api/v1/dns/zones — body: name (required). Returns 201.
curl -k -X POST "$NODE/api/v1/dns/zones" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name":"app-net.internal"}'
{ "status": "created", "zone": { "id": 1, "name": "app-net.internal.", "soa": "ns.app-net.internal.", "serial": 2026063001 } }
Delete a zone
DELETE /api/v1/dns/zones/{id} — removes the zone and every record in it.
Names under the zone stop resolving immediately.
curl -k -X DELETE "$NODE/api/v1/dns/zones/1" -H "Authorization: Bearer $TOKEN"
{ "status": "deleted", "id": 1 }
Deleting a zone that does not exist returns 404.
List records
GET /api/v1/dns/records — lists all records, or one zone's with ?zone_id=N.
curl -k "$NODE/api/v1/dns/records?zone_id=1" -H "Authorization: Bearer $TOKEN"
{ "records": [ { "id": 5, "zone_id": 1, "name": "api", "type": "A", "value": "10.20.0.55", "ttl": 300 } ] }
Create a record
POST /api/v1/dns/records — body: zone_id, name, type, value required;
ttl and source_subnet optional. Returns 201.
curl -k -X POST "$NODE/api/v1/dns/records" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"zone_id":1,"name":"db","type":"A","value":"10.20.0.10","ttl":300}'
{ "status": "created", "record": { "id": 6, "zone_id": 1, "name": "db", "type": "A", "value": "10.20.0.10", "ttl": 300 } }
Update a record
PUT /api/v1/dns/records/{id} — changes a record in place, keeping its id. Body:
name, type and value (required), and ttl and source_subnet (left out:
kept; "" clears the subnet). The change is made in one step and raises the
zone's serial. A record stays in its zone: a zone_id that is not the record's own
is 400. Answers the record as stored; an unknown id is 404.
curl -k -X PUT "$NODE/api/v1/dns/records/6" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name":"db","type":"A","value":"10.20.0.11"}'
Delete a record
DELETE /api/v1/dns/records/{id}
curl -k -X DELETE "$NODE/api/v1/dns/records/6" -H "Authorization: Bearer $TOKEN"
{ "status": "deleted", "record_id": 6 }
Deleting a record that does not exist returns 404.
DNSSEC material for a zone
GET /api/v1/dns/dnssec/{zone} — returns the zone's DNSKEY set and the DS
record to publish in the parent zone. It is a read: it never makes keys. A zone's
keys are made when DNSSEC signing is turned on in the node's configuration
(dnssec_enabled), and for a zone created while it is on; a zone without keys
answers an empty dnskey list with a note. A name that is not a zone on this
node is 404. Answers that a name or a record does not exist are not signed, so
once the DS is published, validating resolvers reject those answers.
curl -k "$NODE/api/v1/dns/dnssec/app-net.internal" -H "Authorization: Bearer $TOKEN"
{
"zone": "app-net.internal.",
"enabled": true,
"dnskey": [
"app-net.internal.\t3600\tIN\tDNSKEY\t257 3 15 <base64-public-key>",
"app-net.internal.\t3600\tIN\tDNSKEY\t256 3 15 <base64-public-key>"
],
"ds": "app-net.internal.\t3600\tIN\tDS\t12345 15 2 <hex-digest>"
}
Forwarders
GET /api/v1/dns/forwarders lists the upstream resolvers that answer names
outside this node's zones (one on port 53 is shown as its bare address).
PUT /api/v1/dns/forwarders replaces the list and saves it, so it is kept across
restarts:
curl -k -X PUT "$NODE/api/v1/dns/forwarders" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"forwarders":["1.1.1.1","192.0.2.53:5353"]}'
{ "forwarders": ["1.1.1.1", "192.0.2.53:5353"] }
A forwarder named more than once is kept once, where it is first named
(1.1.1.1 and 1.1.1.1:53 are one forwarder), as dns forwarder set keeps it.
An empty list is 400: at least one forwarder is needed; without one, names
outside this server's zones cannot be answered. So is a list of more than 8,
counted after the repeats are dropped. A forwarder that is this node's own DNS
server is 409: every outside question would come back to the node without
end.
Static & policy routing
Two related surfaces: routes placed in the kernel forwarding table (optionally a non-main table id), and the policy rules that steer matched traffic into a table.
Route fields: destination (required CIDR), gateway, interface,
metric (0 to 4294967295; the route reaches the server with it), table (0 =
the main table; use a positive id for policy routing).
A route needs a gateway, an interface or both, and a gateway of the destination's
address family. So that no route can cut the server off, a default route cannot be
added to the main table (put it in a table of its own and send traffic to it with
a rule), no route can be added to the local table (255), and a new route never
replaces one the server already has: a route to the same destination with the same
metric is 409.
A static route in the main table that would carry part of the server's own
network, its default gateway or one of its addresses another way is refused, and
so is one that contains them unless it leaves through the default route's own
gateway. So the default route cannot be overridden by more specific routes such as
0.0.0.0/1 with 128.0.0.0/1: the half that holds the server's own network is
refused. Route the networks around the server's own network instead. A route to
any other network is accepted, whatever its size.
A policy rule that would send the server's own traffic to a table ahead of the
main table is refused when that table holds a route over the server's own network,
gateway or addresses. That covers traffic from its management addresses or from
all, arriving on lo, leaving through a device it is reached through, or to its
own network or everywhere. A table whose only route is a default route counts,
even one via the server's own gateway: the table holds none of the networks the
server reaches directly. A route into a table such a rule points at is refused the
same way. A rule into the main or local table, or one after the main table's rule,
is never refused for what it selects.
A stored route or rule these checks refuse stays on record but is not applied when
the server starts; the listing says so under not_enforced. Each refusal says what the route
or rule would take, and that nothing was changed.
List routes
GET /api/v1/routes — optional ?table=N filter.
curl -k "$NODE/api/v1/routes" -H "Authorization: Bearer $TOKEN"
{ "routes": [ { "id": 1, "destination": "10.50.0.0/24", "gateway": "10.20.0.254", "interface": "", "metric": 100, "table": 0 } ] }
Create a route
POST /api/v1/routes — destination required; gateway, interface, metric,
table optional (table must be >= 0). Returns 201.
curl -k -X POST "$NODE/api/v1/routes" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"destination":"0.0.0.0/0","gateway":"203.0.113.1","table":100}'
{ "status": "created", "route": { "id": 2, "destination": "0.0.0.0/0", "gateway": "203.0.113.1", "interface": "", "metric": 0, "table": 100 } }
Delete a route
DELETE /api/v1/routes/{id} → { "status": "deleted", "id": 2 }.
List policy rules
GET /api/v1/routes/rules — the rules that direct matched traffic into a table.
curl -k "$NODE/api/v1/routes/rules" -H "Authorization: Bearer $TOKEN"
{ "rules": [ { "id": 1, "priority": 100, "from": "10.20.0.0/24", "to": "", "fwmark": 0, "iif": "", "oif": "", "table": 100 } ] }
Create a policy rule
POST /api/v1/routes/rules — priority and table are each from 1 to
2147483647 (priority 0 belongs to the local table), at least one selector
(from, to, fwmark, iif, oif) is required, and from and to must be of
one address family. A rule that would take the server's own traffic away is
409 (see above). Returns 201.
curl -k -X POST "$NODE/api/v1/routes/rules" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"priority":100,"from":"10.20.0.0/24","table":100}'
{ "status": "created", "rule": { "id": 1, "priority": 100, "from": "10.20.0.0/24", "to": "", "fwmark": 0, "iif": "", "oif": "", "table": 100 } }
Delete a policy rule
DELETE /api/v1/routes/rules/{id} → { "status": "deleted", "id": 1 }.
Port forwarding
Forward an inbound public address:port to an internal target (destination NAT). This is how you publish an internal service on a public address.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/forward | List port-forward rules |
| POST | /api/v1/forward | Create a port-forward rule |
| GET | /api/v1/forward/{id} | Get one port-forward rule |
| DELETE | /api/v1/forward/{id} | Delete a port-forward rule |
Create — body: dest_port (the inbound match), target_ip, target_port
(the internal target, an IPv4 address) required; dest_ip optional. Ports are 1 to
- Returns 201.
Port forwards are TCP only (a protocol other than tcp is 400) and need a
masquerade rule: a forward answers on the IPv4 address of the first masquerade
rule's interface, and every answer names it as answers_on. With no masquerade
rule, with a dest_ip that is not that address, or for a TCP port of it that is
already forwarded, the forward is 409. A forward saved before these checks that
is never reached lists not_enforced.
A forward of a port the server itself serves is 409 too: TCP ports 7070 to
7074, the configured REST, gRPC and WebSocket ports, and any port a program on the
server listens on at the address the forward answers on, or on every address (such
as SSH on 22, or a BGP speaker on 179). A forward is translated before the server
sees the connection, so it would take that service's connections. A port nothing
on the server serves can be forwarded. A stored forward of one of the server's
management ports is not applied when the server starts, and lists not_enforced.
curl -k -X POST "$NODE/api/v1/forward" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"dest_ip":"203.0.113.10","dest_port":443,"target_ip":"10.20.0.10","target_port":8443}'
{
"status": "created",
"port_forward": { "id": 5, "protocol": "tcp", "dest_ip": "203.0.113.10", "dest_port": 443, "target_ip": "10.20.0.10", "target_port": 8443 },
"answers_on": "203.0.113.10"
}
List returns only port forwards — masquerade rules are listed under
/api/v1/gateway/snat:
{ "port_forwards": [ { "id": 5, "protocol": "tcp", "dest_ip": "203.0.113.10", "dest_port": 443, "target_ip": "10.20.0.10", "target_port": 8443 } ], "answers_on": "203.0.113.10" }
GET /api/v1/forward/5 returns { "port_forward": { ... } }, or 404 when no
port forward has that id. Delete → DELETE /api/v1/forward/5 returns
{ "status": "deleted", "id": 5 }, or the same 404 when no port forward has
that id. Port forwards and masquerade rules are numbered from one shared
sequence, so a masquerade rule's id is not a port forward: remove those with
DELETE /api/v1/gateway/snat/{id}.
VLAN lockdown
A per-VLAN allow/deny table for the tenant network. An empty table means every VLAN is allowed (the default). Add a row with allowed: false to lock a VLAN
down; allowed: true records an explicit allow.
List VLAN policies
GET /api/v1/vlan
curl -k "$NODE/api/v1/vlan" -H "Authorization: Bearer $TOKEN"
{ "vlans": [ { "vlan_id": 200, "allowed": false } ] }
Set a VLAN policy
POST /api/v1/vlan — body: vlan_id (required, 1–4094) and allowed.
Returns 201.
curl -k -X POST "$NODE/api/v1/vlan" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"vlan_id":200,"allowed":false}'
{ "status": "set", "vlan": { "vlan_id": 200, "allowed": false } }
Clear a VLAN policy
DELETE /api/v1/vlan/{id} — removes the row, returning that VLAN to the default.
curl -k -X DELETE "$NODE/api/v1/vlan/200" -H "Authorization: Bearer $TOKEN"
{ "status": "cleared", "vlan_id": 200 }
VXLAN overlays
Layer-2 overlay networks keyed by VNI (a 24-bit id, 1–16777215) plus their remote peers (VTEPs). (Plan feature: VXLAN.)
List overlay networks
GET /api/v1/vxlan/networks
curl -k "$NODE/api/v1/vxlan/networks" -H "Authorization: Bearer $TOKEN"
{
"vxlan_networks": [
{ "vni": 1001, "subnet": "10.200.0.0/24", "peers": [ { "host": "node-b", "mac": "", "vtep_ip": "198.51.100.20" } ], "binding_conflicts": 0 }
]
}
binding_conflicts counts the peers that the cluster shares with this server whose MAC address is also held by a MAC binding on this server. The overlay leaves such an address to the binding and keeps the peer on record; once the binding is removed, the overlay takes the address. It is 0 when no shared peer conflicts with a binding.
The listing also says whether this server checks overlay traffic against its peers: peer_check_enforced is true when the check is on, so an overlay frame is accepted only from a peer its network lists. When it is false, the server accepts overlay frames from any source for its networks, and you should fix that before you rely on those networks.
Create an overlay network
POST /api/v1/vxlan/networks — body: vni (required, 1–16777215) and
subnet. Returns 201.
curl -k -X POST "$NODE/api/v1/vxlan/networks" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"vni":1001,"subnet":"10.200.0.0/24"}'
{ "status": "created", "vni": 1001, "subnet": "10.200.0.0/24", "device": "cnv-vx1001", "device_state": "up" }
The answer and the listing say whether the network's overlay device is up,
down or missing (it is made again at the next start), or why it is not built
— the server has no address for the overlay to leave from. The subnet is kept
across restarts. A device the server refuses to build leaves nothing behind.
Delete an overlay network
DELETE /api/v1/vxlan/networks/{vni} → { "status": "deleted", "vni": 1001 }.
List peers
GET /api/v1/vxlan/networks/{vni}/peers
{ "vni": 1001, "peers": [ { "host": "node-b", "mac": "", "vtep_ip": "198.51.100.20" } ] }
Add a peer
POST /api/v1/vxlan/networks/{vni}/peers — body: host and vtep_ip
(both required), mac optional. Returns 201. vtep_ip must be an IP
address and mac, when given, a valid MAC; anything else is 400. A peer with
no mac still works: the node sends broadcast and unknown traffic (which carries
ARP) to its VTEP and learns the addresses behind it from the replies.
curl -k -X POST "$NODE/api/v1/vxlan/networks/1001/peers" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"host":"node-b","vtep_ip":"198.51.100.20"}'
{ "status": "added", "vni": 1001, "host": "node-b" }
Remove a peer
DELETE /api/v1/vxlan/networks/{vni}/peers/{host} →
{ "status": "removed", "vni": 1001, "host": "node-b" }.
Forwarding database
GET /api/v1/vxlan/fdb — the overlay MAC-to-VTEP forwarding table.
{ "fdb": [ { "mac": "02:ce:0a:c8:00:05", "vni": 1001, "vtep_ip": "198.51.100.20" } ] }
Firewall rules & connection tracking
Manage the node's firewall rule table. Each rule matches on protocol,
source/destination address and port, ingress interface, and optionally a source
MAC, and allows or drops what it matches. Rules are checked on traffic as it
arrives on the workload bridge and on the node's forwarding interfaces
(gateway_wan_interface and gateway_lan_interface), whether it is for the node
itself or routed through it, before address translation. Where the uplink is not
one of those interfaces — on a node with none configured, for example — traffic
arriving on it is checked only against the blocked-address list, not against
these rules. Nor are they checked on traffic two workloads on the same network
exchange directly. Rules are stateful for TCP and UDP: once a connection's first
packet is admitted, its replies and later packets are admitted without being
checked again. An IPv4 ping sent out through the node's address translation has
its reply admitted the same way. Other traffic — other protocols, ICMP error
messages, and the fragments of a packet after the first — is judged by the rules
in each direction, so with the default action at deny it needs its own allow
rule. A connection the node itself opens, or one whose first packet arrived on
an uplink these rules do not cover, is not remembered (see
Firewall). To view tracked
connections, see the Traffic visibility → Flows section below.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/rules | List rules (optional ?chain= filter) |
| POST | /api/v1/rules | Create a rule |
| GET | /api/v1/rules/{id} | Get one rule |
| PUT | /api/v1/rules/{id} | Replace a rule (validated first; a new id is assigned) |
| DELETE | /api/v1/rules/{id} | Delete a rule |
| GET | /api/v1/rules/default | The default action for traffic no rule matches: {"default_action":"allow"} or "deny" |
| PUT | /api/v1/rules/default | Set it: body {"default_action":"deny"} (or "allow") |
Rule fields
| Field | Type | Notes |
|---|---|---|
id | integer | Assigned by the node (response only) |
action | string | Required. accept or drop |
priority | integer | Evaluation priority |
protocol | string | tcp, udp or icmp (omit for any). icmp is IPv4 ICMP only and takes no ports |
source_ip / dest_ip | string | Address or CIDR; both the same family when both are given |
source_port / dest_port | integer | A single port; a port rule matches TCP and UDP only |
dest_port_max | integer | Makes dest_port the start of an inclusive range |
interface | string | Bind the rule to one ingress device (e.g. cnv-user-br0) |
mac | string | Match a source MAC (aa:bb:cc:dd:ee:ff); omit for any |
level | string | Policy scope, which sets the order rules are checked in: global (default), bridge (or its synonym interface), vlan, private_network, mac, flow — broadest first. See Firewall |
comment | string | Free text |
chain | string | Optional; the only value is prerouting (where every rule applies) |
stateful | boolean | Optional; the only value is true: a rule cannot be made stateless. What is remembered is described above |
A body is decoded strictly: an unrecognised key is 400, naming the key, so a
misspelt matcher cannot silently widen a rule. So are an address, MAC or
protocol that cannot be read, a chain other than prerouting, stateful:
false, and the action reject — none of these is enforced, so none is
accepted.
On a member of a cluster, a drop rule whose source_ip is a member's address
is refused when it could drop the cluster's own traffic: POST and PUT
answer 409, and in POST /api/v1/rules/batch that rule fails while the
others are added. See
Members' addresses are never blocked.
Empty/zero optional fields are omitted from responses; id, chain, priority,
action, and stateful always appear. A rule saved before these checks that
still carries a setting that is not enforced is returned with not_enforced
(a list of {field, detail}) and, when the node leaves it out entirely,
"not_applied": true — see Rules saved before these checks.
Create a rule
curl -k -X POST "$NODE/api/v1/rules" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"action": "drop",
"priority": 100,
"protocol": "tcp",
"source_ip": "198.51.100.0/24",
"dest_port": 22,
"comment": "block ssh from that net"
}'
{
"status": "created",
"rule": { "id": 7, "chain": "prerouting", "priority": 100, "protocol": "tcp", "source_ip": "198.51.100.0/24", "dest_port": 22, "action": "drop", "comment": "block ssh from that net", "stateful": true }
}
List rules (optionally filter by chain — useful to find rules saved under
another chain before these checks, e.g. ?chain=forward):
curl -k "$NODE/api/v1/rules" -H "Authorization: Bearer $TOKEN"
{ "rules": [ { "id": 7, "chain": "prerouting", "priority": 100, "protocol": "tcp", "source_ip": "198.51.100.0/24", "dest_port": 22, "action": "drop", "comment": "block ssh from that net", "stateful": true } ] }
Replace a rule. There is no in-place edit; PUT replaces the old rule with
the new one, which receives a new id (returned in the response). The body
uses the same fields as create (action required).
- The replacement is validated before anything changes, and the swap is a single step: an invalid body is 400, a replacement that does not fit is 409, and in either case the existing rule stays exactly as it was.
- An unknown id is 404.
- A schedule on the old rule carries over to the replacement.
- This is how to correct a rule listed with
not_enforced.
curl -k -X PUT "$NODE/api/v1/rules/7" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"action":"drop","priority":100,"protocol":"tcp","source_ip":"198.51.100.0/24","dest_port":22,"comment":"no ssh from that net"}'
{ "status": "updated", "rule": { "id": 8, "chain": "prerouting", "priority": 100, "protocol": "tcp", "source_ip": "198.51.100.0/24", "dest_port": 22, "action": "drop", "comment": "no ssh from that net", "stateful": true } }
Default action. The verdict for traffic no rule matches. It starts as
allow; set deny to refuse whatever no rule allows, once your allow rules are in place
(including your own access to the node, and replies to connections the node
opens itself — see The default action).
curl -k -X PUT "$NODE/api/v1/rules/default" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"default_action":"deny"}'
{ "status": "set", "default_action": "deny" }
Delete a rule: DELETE /api/v1/rules/8 → { "status": "deleted", "id": 8 }.
Setting the default action needs the firewall in the node's plan. A default action that cannot be saved is refused, and the running one stays as it was.
Schedules, connection limits, the connection table and the blocklist
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/firewall/schedules | Every rule's schedule, with open for whether its window is open now |
| PUT | /api/v1/firewall/schedules/{rule} | Set a rule's schedule: {"days":["mon","tue"],"start":"08:00","end":"18:00"}, in UTC |
| DELETE | /api/v1/firewall/schedules/{rule} | Clear it: the rule is always active again |
| GET | /api/v1/firewall/connlimit | The connection limit, and blocked_now |
| PUT | /api/v1/firewall/connlimit | Set it: {"max_per_source":200,"block_secs":300} (block_secs defaults to 600) |
| DELETE | /api/v1/firewall/connlimit | Turn it off |
| GET | /api/v1/firewall/conntrack | The connection table: up to 1,000 entries (?source=, ?limit=), with truncated |
| POST | /api/v1/firewall/conntrack/flush | Flush it, or with {"source":"<address>"} the entries that address is either end of |
| GET | /api/v1/firewall/blocklist | The addresses the node blocks on its own, with each one's source and expires_at |
| DELETE | /api/v1/firewall/blocklist/{address} | Lift an automatic block now |
A schedule's days are given by name (mon … sun; none means every day) and its
window as HH:MM in UTC (none means the whole day; the end minute is included).
Each schedule carries a note: a window applies to new connections only. The rule
listing shows each rule's schedule. Changing a schedule or the connection limit
needs the firewall in the node's plan; the connection table answers 503
without the packet filter running. Lifting a block works whatever
the state of the licence: an address that is not blocked is 404, and a block
from the rule list is 409 — remove the rule instead. What each of these does is
on the Firewall page.
Load balancer
L4 virtual IPs (VIPs) with a pool of backends. Create a VIP, attach/detach backends, override backend health, take a backend out of rotation, and optionally configure an active health check. (Plan feature: Load Balancer.)
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/lb | List VIPs |
| POST | /api/v1/lb | Create a VIP |
| GET | /api/v1/lb/{id} | Get one VIP |
| PUT | /api/v1/lb/{id} | Not supported — returns 501 |
| DELETE | /api/v1/lb/{id} | Delete a VIP |
| POST | /api/v1/lb/{id}/backends | Add a backend |
| DELETE | /api/v1/lb/{id}/backends/{bid} | Remove a backend |
| POST | /api/v1/lb/{id}/backends/{bid}/health | Manually set a backend up/down |
| PUT | /api/v1/lb/{id}/backends/{bid}/admin | Take a backend out of rotation, or put it back |
VIP fields — id, frontend_ip, frontend_port, protocol and algorithm are required on create.
| Field | Type | Notes |
|---|---|---|
id | string | Your VIP identifier |
frontend_ip | string | The virtual IP, an IPv4 address |
frontend_port | integer | From 1 to 65535 |
protocol | string | tcp or udp |
algorithm | string | round-robin, source-hash, weighted, maglev, consistent-hash (see Load Balancer for what each does) |
dsr_enabled | boolean | Refused when true: replies always pass back through the load balancer |
health_check | object | Optional active check (see below) |
least-conn is refused. A VIP's answer also carries not_enforced: settings of a
stored VIP not enforced as written, each with its field and what happens instead.
Only a VIP created before this release can have one: with least-conn (served
round-robin), with dsr_enabled (replies still pass back through the load
balancer), with an address or port now refused (frontend_ip, frontend_port,
or backends.<id> for one backend: it takes no traffic), or with more backends
than its algorithm takes (backends).
health_check: type (tcp, http or https; empty disables it; any other
type is refused), interval_sec (from 1 to 3600; 5 if left out), timeout_sec
(from 1 to 60; 3 if left out), threshold (1 if left out) and http_path (for
http and https only; / if left out). An http check speaks plain HTTP to the
backend's own address and port and an https check speaks HTTPS, without
verifying the backend's certificate. A redirect counts as an answer and is not
followed.
Create a VIP with an HTTP health check:
curl -k -X POST "$NODE/api/v1/lb" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"id": "web-vip",
"frontend_ip": "203.0.113.10",
"frontend_port": 80,
"protocol": "tcp",
"algorithm": "round-robin",
"dsr_enabled": false,
"health_check": { "type": "http", "interval_sec": 10, "timeout_sec": 2, "threshold": 3, "http_path": "/healthz" }
}'
{
"status": "created",
"load_balancer": { "id": "web-vip", "frontend_ip": "203.0.113.10", "frontend_port": 80, "protocol": "tcp", "algorithm": "round-robin", "dsr_enabled": false, "backends": [] }
}
Add a backend (id, ip and port required; id need only be unique within
the VIP; weight drives the weighted algorithm's share). A VIP takes at most 64
backends, or 61 with source-hash, maglev or consistent-hash; one more is
refused, and so is an address that is not IPv4 or a port outside 1 to 65535:
curl -k -X POST "$NODE/api/v1/lb/web-vip/backends" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"id":"app-1","ip":"10.0.0.11","port":80,"weight":1}'
{ "status": "added", "vip_id": "web-vip", "backend_id": "app-1" }
Get a VIP (shows backends with live health):
{
"load_balancer": {
"id": "web-vip", "frontend_ip": "203.0.113.10", "frontend_port": 80, "protocol": "tcp", "algorithm": "round-robin", "dsr_enabled": false,
"backends": [ { "id": "app-1", "ip": "10.0.0.11", "port": 80, "weight": 1, "healthy": true, "admin_state": "in" } ]
}
}
admin_state is in, or out while the backend is out of rotation.
Override a backend's health (the state is saved and holds when the node
restarts; a configured active check can change it back). healthy is required: a
body without it is refused with 400. A change that cannot be saved is refused
with 500 and changes nothing; an unknown VIP or backend answers 404:
curl -k -X POST "$NODE/api/v1/lb/web-vip/backends/app-1/health" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"healthy": false}'
{ "status": "set", "vip_id": "web-vip", "backend_id": "app-1", "healthy": false }
Take a backend out of rotation ({"state": "out"}), or put it back
({"state": "in"}). Out of rotation, the backend takes no connections: new ones
and the ones already on it go to the other backends at once, which breaks TCP
connections. A health check never puts it back, and the state is saved before it
is applied, so it holds when the node restarts. Back in rotation, it takes new
connections once it is healthy. The answer is the backend, with a note saying
what happened to connections. Any other body answers 400, an unknown VIP or
backend 404, and a change that cannot be saved 500, changing nothing:
curl -k -X PUT "$NODE/api/v1/lb/web-vip/backends/app-1/admin" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"state": "out"}'
{ "id": "app-1", "address": "10.0.0.11", "port": 80, "healthy": true, "admin_state": "out", "note": "new and existing connections now go to the other backends" }
Remove a backend → { "status": "removed", "vip_id": "web-vip", "backend_id": "app-1" }.
Delete a VIP → { "status": "deleted", "id": "web-vip" }.
A VIP cannot be edited in place. PUT /api/v1/lb/{id} returns 501:
{ "error": "updating a VIP in place is not supported; delete and recreate it" }
HTTP load balancer (layer 7)
Pools of HTTP backends, and frontends that route each request to a pool by host
and path, optionally terminating TLS (see
Load Balancer).
(Plan feature: Load Balancer, reads included.) Reading needs Sys.Audit on the
node and a change needs Sys.Modify.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/l7lb/status | Every frontend and pool, with each backend's health and requests in progress |
| GET | /api/v1/l7lb/pools | List pools |
| GET | /api/v1/l7lb/frontends | List frontends |
| POST | /api/v1/l7lb/pools | Create a pool (201), or change an existing one's algorithm and health check (200) |
| DELETE | /api/v1/l7lb/pools/{name} | Remove a pool that no frontend routes to |
| GET | /api/v1/l7lb/pools/{name}/backends | A pool's backends, live |
| POST | /api/v1/l7lb/pools/{name}/backends | Add a backend (201; 200 when the pool already has it) |
| DELETE | /api/v1/l7lb/pools/{name}/backends/{backend} | Remove a backend, by its id |
| POST | /api/v1/l7lb/frontends | Create a frontend (201) |
| DELETE | /api/v1/l7lb/frontends/{name} | Remove a frontend |
Pool fields — name is required: 1 to 64 letters, digits, ., _ or -,
starting with a letter or digit.
| Field | Type | Notes |
|---|---|---|
algorithm | string | round-robin (if left out) or least-connections |
backends | array | {"id", "address"} each; address is host:port, and id is optional: the first free one of b1, b2, … |
health | object | path, interval_sec, timeout_sec, healthy_threshold, unhealthy_threshold. Left out, each takes its default: /, every 10 seconds, a 2-second timeout, 2 passes in a row to return and 3 failures in a row to leave. A negative value is refused |
For a pool that already exists, naming backends other than the ones it has is
refused with 409: add and remove them one at a time.
Frontend fields — name (the same rule as a pool's) and listen are
required.
| Field | Type | Notes |
|---|---|---|
listen | string | host:port, or :port for every address. Port 0 is refused, and so are the ports the server's own services use (409): 7070 to 7074 and the configured REST, gRPC and WebSocket ports |
tls | object | Left out for plain HTTP, otherwise {"certificate_pem": "...", "key_pem": "..."}: the certificate chain and its key as PEM, each at most 64 KiB. {"use_managed": true} is refused with 400: the node's own certificate goes on a frontend only on the node's command line |
routes | array | {"host", "path_prefix", "pool"} each, checked in order |
default_pool | string | Where a request that matches no route goes |
timeouts | object | connect_sec, response_sec, idle_sec |
A certificate is never a path: cert_file and key_file are refused over the
API, and so is a certificate and key that are not a matching pair. The node keeps
the certificate and key itself, never returns them in any answer, and deletes them
when the frontend is removed.
curl -k -X POST "$NODE/api/v1/l7lb/pools" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name": "web", "backends": [{"address": "10.20.0.50:8080"}, {"id": "web-2", "address": "10.20.0.51:8080"}]}'
curl -k -X POST "$NODE/api/v1/l7lb/frontends" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name": "https", "listen": ":443", "default_pool": "web",
"tls": {"certificate_pem": "-----BEGIN CERTIFICATE-----\n…", "key_pem": "-----BEGIN PRIVATE KEY-----\n…"}}'
What the reads show. A pool is name, algorithm, backends (id,
address, healthy) and health with the defaults applied, plus error for a
saved pool that could not be loaded. A frontend is name, listen, listening,
error, tls, routes, default_pool and timeouts with the defaults
applied. Its tls is null for plain HTTP, otherwise use_managed and
has_certificate, never where a certificate is kept. use_managed is true for a
frontend made on the node's command line with the node's own certificate. A pool
adds managed_frontends, the frontends with the node's own certificate that
route to it, when there are any; such a pool cannot be changed over the API, and
such a frontend can only be removed. error is a fixed phrase
saying why a frontend is not listening or a pool is not loaded, such as "the
address is in use", never the system's message. The status and a pool's live
backends add requests_in_progress to each backend: requests being passed to it
now, not connections. Intervals and timeouts are whole seconds.
A refusal answers 400 for a request as written, 404 for a pool, backend or
frontend that does not exist, 409 when it clashes with what exists (a frontend
name taken, a backend id the pool already uses, an address the pool already has
under another id, a pool still in use, a pool that a frontend with the node's own
certificate routes to, a port the server's own services use),
and 500 when the node cannot store or save the change. Its error never names
a path or the system's message.
BGP & route filtering
Peer with upstream routers, advertise and withdraw prefixes, and shape what you accept/announce with prefix-lists, route-maps, and per-neighbor import/export policy. (Plan feature: BGP.)
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/bgp/status | Engine summary |
| GET | /api/v1/bgp/neighbors | List peers |
| POST | /api/v1/bgp/neighbors | Add a peer |
| DELETE | /api/v1/bgp/neighbors/{addr} | Remove a peer |
| GET | /api/v1/bgp/routes | Route table (?family=ipv4 default, or ipv6; anything else is 400) |
| POST | /api/v1/bgp/announce | Advertise a prefix |
| POST | /api/v1/bgp/withdraw | Withdraw a prefix |
| GET | /api/v1/bgp/prefix-lists | List prefix-lists |
| POST | /api/v1/bgp/prefix-lists | Create a prefix-list |
| GET | /api/v1/bgp/route-maps | List route-maps |
| POST | /api/v1/bgp/route-maps | Create a route-map |
| GET | /api/v1/bgp/policy | Show import/export policy bindings |
| POST | /api/v1/bgp/policy/{dir} | Bind a route-map ({dir} = import or export) |
| GET | /api/v1/bgp/rib | One of the three route tables (?table=in, local or out) |
| GET / PUT | /api/v1/bgp/rpki | Route-origin validation: its status, and its settings |
| GET | /api/v1/bgp/rpki/validate | How one prefix and origin AS validate now |
| GET / PUT | /api/v1/bgp/evpn | The EVPN address family: its status, and on or off |
| GET | /api/v1/bgp/evpn/routes | The EVPN routes this node originates and has learned |
A refusal says what is wrong: 400 for a value that is not valid, 404 for a neighbour, route-map or announcement the node does not have, 409 for a neighbour it already has, and 500 only for a change that could not be saved (nothing changed).
Status:
curl -k "$NODE/api/v1/bgp/status" -H "Authorization: Bearer $TOKEN"
{ "status": "running", "neighbors": 2, "routes": 17, "bfd_sessions_up": 0 }
BFD is not available, so bfd_sessions_up is always 0.
Add a peer. peer_addr, peer_as, and local_as are required. Optional:
hold_time (3 to 65535 seconds; 90 when left out), keepalive_interval (1 up
to a third of the hold time; a third of it when left out), and md5_key (TCP MD5
signing of the session, at most 80 bytes; never returned in reads). BFD settings
(bfd_enabled, bfd_interval_ms, bfd_multiplier) are refused with 400: a
lost neighbour is noticed when its hold time runs out. The answer is 201 with
the neighbour as the node holds it, md5_enabled in place of the key.
curl -k -X POST "$NODE/api/v1/bgp/neighbors" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"peer_addr": "192.0.2.1", "peer_as": 64512, "local_as": 64513,
"hold_time": 90, "keepalive_interval": 30, "md5_key": "a-shared-secret"
}'
List peers (state is one of Idle, Connect, Active, OpenSent,
OpenConfirm, Established):
{
"neighbors": [
{
"id": "192.0.2.1", "peer_as": 64512, "local_as": 64513, "peer_addr": "192.0.2.1",
"state": "Established", "hold_time": 90, "keepalive_interval": 30,
"md5_enabled": true, "bfd_enabled": false,
"last_state_change": "2026-06-30T11:58:02Z", "messages_in": 412, "messages_out": 410,
"graceful_restart": false, "peer_graceful_restart": false
}
]
}
A neighbour saved with a setting the node does not carry out (BFD, or a TCP MD5
key the system cannot put in place) lists it under not_enforced.
Remove a peer → DELETE /api/v1/bgp/neighbors/192.0.2.1 returns
{ "status": "deleted", "addr": "192.0.2.1" }. Its import and export policies
are removed with it.
Advertise a prefix (prefix required, an IPv4 CIDR; next_hop and
communities optional). Without a next hop, each peer is sent this node's own
address on that session. A community is asn:value (each 0–65535) or one of
no-export, no-advertise, no-export-subconfed, no-peer. The announcement
reaches established peers at once:
curl -k -X POST "$NODE/api/v1/bgp/announce" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"prefix":"203.0.113.0/24","next_hop":"192.0.2.254","communities":["64512:100"]}'
{ "status": "announced", "prefix": "203.0.113.0/24" }
Withdraw a prefix: POST /api/v1/bgp/withdraw with {"prefix":"203.0.113.0/24"}
returns { "status": "withdrawn", "prefix": "203.0.113.0/24" }.
GET /api/v1/bgp/routes returns the current route table as
{ "routes": [ ... ], "family": "ipv4" }. Each route carries its next hop, AS
path, communities, local-preference, MED, and origin.
One table. GET /api/v1/bgp/rib takes table — in (what each peer sent
that the node accepted), local (the routes it selected, its own included; the
default) or out (what it announces; with neighbor, what that peer's session
has actually been sent, empty while no session is up) — and prefix, which keeps
the routes equal to or inside a prefix, or those covering an address. At most
1,000 routes; truncated says there were more. An unknown neighbor is 404.
curl -k "$NODE/api/v1/bgp/rib?table=in&prefix=203.0.113.0/24" -H "Authorization: Bearer $TOKEN"
{
"table": "in",
"routes": [
{
"prefix": "203.0.113.0/24", "next_hop": "192.0.2.1", "neighbor": "192.0.2.1",
"as_path": [64500, 64501], "origin": "igp", "local_pref": 100, "med": 0,
"communities": ["64500:100"], "best": true, "stale": false, "rpki": "valid", "age_seconds": 3600
}
],
"truncated": false
}
Route-origin validation (RPKI)
GET /api/v1/bgp/rpki reports the cache (rtr_address, connection_state:
inactive, connecting, connected or error), the set the held routes are
judged against (serial, vrp_count — the records in effect, 0 once the set
has expired, last_sync) and validation_counts, the routes held now counted by
state.
PUT /api/v1/bgp/rpki sets it: enabled is required; leaving out rtr_address
keeps the configured cache, and leaving out reject_invalid keeps the policy.
Every held route is judged again under the result before the answer, which is the
status:
curl -k -X PUT "$NODE/api/v1/bgp/rpki" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"enabled":true,"rtr_address":"192.0.2.10:323","reject_invalid":true}'
{
"enabled": true, "rtr_address": "192.0.2.10:323", "reject_invalid": true,
"connection_state": "connected", "session_id": 7, "serial": 1234, "vrp_count": 456789,
"refresh_seconds": 3600, "last_sync": "2026-10-11T08:59:00Z",
"validation_counts": { "valid": 120, "invalid": 3, "not_found": 40 }
}
GET /api/v1/bgp/rpki/validate?prefix=192.0.2.0/24&origin_as=64500 answers
{"state": "valid"} (or invalid, not-found) against the set in effect now,
without counting it; with validation off it is not-found.
EVPN
GET /api/v1/bgp/evpn reports the address family's state, with
"forwarding": false: the node exchanges and learns EVPN routes and does not use
them to forward traffic. PUT /api/v1/bgp/evpn takes {"enabled": true, "vtep":
"10.0.0.1", "rd": "65000:100"} (enabled is required; a missing vtep or rd
keeps the configured one) or {"enabled": false}. When peerings are up, the
answer's note says they offer the change the next time they are established.
GET /api/v1/bgp/evpn/routes lists the routes this node originates and the ones it
has learned (local_macs, remote_macs, remote_vteps, local_vnis).
Prefix-lists
A named, ordered list of CIDR matchers used by route-maps. name is required;
each entry has prefix (CIDR), action, and optional ge/le prefix-length
bounds. action is allow or permit, deny or block, in any letter case (an
empty action is an allow); any other value is 400, so a typo can never turn a
deny into a permit.
curl -k -X POST "$NODE/api/v1/bgp/prefix-lists" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"name": "customer-routes",
"entries": [
{ "prefix": "203.0.113.0/24", "action": "allow", "ge": 24, "le": 32 },
{ "prefix": "0.0.0.0/0", "action": "deny" }
]
}'
{ "status": "created", "prefix_list": "customer-routes" }
GET /api/v1/bgp/prefix-lists returns { "prefix_lists": [ ... ] }, each with its
name and entries.
Route-maps
A named, sequenced policy that matches routes and sets attributes. name is
required; each entry has seq, action (the same values as a prefix-list
entry; anything else is 400), match_prefix (a prefix-list name), and
optional set_local_pref, set_community, set_med.
curl -k -X POST "$NODE/api/v1/bgp/route-maps" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"name": "prefer-customer",
"entries": [ { "seq": 10, "action": "allow", "match_prefix": "customer-routes", "set_local_pref": 200, "set_community": "64512:100" } ]
}'
{ "status": "created", "route_map": "prefer-customer" }
GET /api/v1/bgp/route-maps:
{
"route_maps": [
{ "name": "prefer-customer", "entries": [ { "seq": 10, "action": "allow", "match_prefix": "customer-routes", "set_local_pref": 200, "set_community": "64512:100", "set_med": 0 } ] }
]
}
Apply import/export policy
Bind a route-map to a neighbor in a direction. {dir} in the path is import or
export; the body needs neighbor and route_map (both required).
curl -k -X POST "$NODE/api/v1/bgp/policy/import" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"neighbor":"192.0.2.1","route_map":"prefer-customer"}'
{ "status": "applied", "direction": "import", "neighbor": "192.0.2.1", "route_map": "prefer-customer" }
GET /api/v1/bgp/policy returns the current bindings as neighbor → route-map maps:
{ "import": { "192.0.2.1": "prefer-customer" }, "export": { "192.0.2.1": "announce-only" } }
NIC bonds
Aggregate physical NICs into a bond for redundancy or throughput. Create a bond, enslave/release member interfaces, and set a consistent MTU across the bond and its members.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/bonds | List bonds |
| POST | /api/v1/bonds | Create a bond |
| GET | /api/v1/bonds/{id} | Get one bond |
| DELETE | /api/v1/bonds/{id} | Delete a bond |
| POST | /api/v1/bonds/{id}/members | Enslave a member NIC |
| DELETE | /api/v1/bonds/{id}/members/{iface} | Release a member NIC |
| PUT | /api/v1/bonds/{id}/mtu | Set the bond+members MTU |
Bond ids that need escaping in a path (such as / or :) work on every bond call.
Create a bond. name and mode are required; mode is active-backup
or 802.3ad (LACP). id is optional — one is generated if omitted. mtu is 68 to
9216, 1500 when left out, and the bond keeps it. A name that an interface on the
server already has is refused (409).
Bonds are rebuilt with their mode, MTU and members when the agent restarts. A
member is refused (409) when it carries the way the server is reached — the
management bridge and its card, the configured uplink, the device a default route
leaves through, the device holding the API's or the cluster's address, and their
ports — or when it has addresses of its own or is already part of a bridge or a
bond. A saved member that the same check refuses at a restart is not put back and
is listed under held, with the reason. Every change is all or nothing.
A bond that carries the way the server is reached or its workloads' way out — the configured uplink or LAN interface, the device a default route leaves through, the one holding the API's or the cluster's address, or a port of the management bridge — cannot be deleted, and its MTU cannot be changed (409; setting the MTU it already has is accepted). A member comes out of such a bond only while it has no link, or is gone, so a failed card can be replaced.
If the server starts before it has a default route, bond members wait for one, for
up to 2 minutes, and are listed under held meanwhile. The card the default route
then leaves through is never taken into a bond. If no default route comes, the
members stay held; to put one back, remove it from the bond and add it again. A
bond that is the configured uplink, or a port of the management bridge, gets its
members back at once.
curl -k -X POST "$NODE/api/v1/bonds" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name":"cnv-bond0","mode":"active-backup","mtu":1500}'
{
"status": "created",
"bond": { "id": "bond-9f2a1c44d0e7b3a8", "name": "cnv-bond0", "mode": "active-backup", "mtu": 1500, "active_slave": "", "members": [] }
}
Enslave a member (member state is active, standby, or failed):
curl -k -X POST "$NODE/api/v1/bonds/bond-9f2a1c44d0e7b3a8/members" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"interface":"cnv-nic-0"}'
{ "status": "enslaved", "id": "bond-9f2a1c44d0e7b3a8", "interface": "cnv-nic-0" }
Get a bond:
{
"bond": {
"id": "bond-9f2a1c44d0e7b3a8", "name": "cnv-bond0", "mode": "active-backup", "mtu": 1500, "active_slave": "cnv-nic-0",
"members": [ { "interface": "cnv-nic-0", "state": "active" }, { "interface": "cnv-nic-1", "state": "standby" } ]
}
}
Set the MTU:
curl -k -X PUT "$NODE/api/v1/bonds/bond-9f2a1c44d0e7b3a8/mtu" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"mtu":9000}'
{ "status": "mtu-set", "id": "bond-9f2a1c44d0e7b3a8", "mtu": 9000 }
Release a member → DELETE /api/v1/bonds/{id}/members/cnv-nic-1 returns
{ "status": "released", "id": "...", "interface": "cnv-nic-1" }.
Delete a bond → { "status": "deleted", "id": "..." }.
Gateway HA & floating IPs
Gateway failover is coming in a later release. You cannot pair two nodes yourself yet, and a floating IP cannot move to another node yet. Until then every node stands alone for failover.GET /api/v1/gateway/statusreports itspeer_stateassolo, and a floating IP stays on the node you assign it on — in a cluster too, where its assignment is recorded on every member. See Gateway High Availability.
For two nodes paired active/standby, these endpoints inspect HA state and
trigger failover/failback. A node with no HA peer is active and holds its
configured VIP itself. Floating IPs are virtual addresses that the server holding
them brings up on the workload bridge.
Gateway HA
(Plan feature: Gateway HA — setting up a pair is coming in a later release.)
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/gateway/status | Current HA state |
| POST | /api/v1/gateway/failover | Take the VIP onto this node |
| POST | /api/v1/gateway/failback | Release the VIP from this node |
The pair's settings come from the node's configuration. While a pair's heartbeat
runs, the two nodes' priorities decide which one holds the VIP, so a manual
failover or failback is refused with 409 (change gateway_priority instead). A
manual switch is for a pair whose heartbeat is not running. A node without a
partner cannot fail back — no node would hold the VIP — and its failover is
refused because it already holds it.
Source NAT (masquerade)
How a private tenant subnet reaches the internet through the node's public
address. Traffic leaving source_cidr via interface is rewritten to that
interface's address, and replies are translated back.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/gateway/snat | List NAT rules |
| POST | /api/v1/gateway/snat | Add a masquerade rule |
| DELETE | /api/v1/gateway/snat/{id} | Remove a rule |
curl -k -X POST "$NODE/api/v1/gateway/snat" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"source_cidr":"10.20.0.0/24","interface":"cnv-nic-1"}'
{ "status": "created", "rule": { "id": 3, "type": "snat", "source_ip": "10.20.0.0/24", "interface": "cnv-nic-1" } }
GET /api/v1/gateway/snat returns { "nat_rules": [ ... ] } with the same rule
objects, using the same field names as gateway snat list on the CLI: id,
type, source_ip, dest_ip, source_port, dest_port and interface. A
field that does not apply to a rule is left out. The list includes port forwards
(type port_forward, with the public address and port in dest_ip /
dest_port and the workload in source_ip / source_port) as well as
masquerade rules (snat). An empty list is [].
Every masqueraded IPv4 range leaves through the first masquerade rule's interface,
and each rule lists the address it leaves as (leaves_as). So a rule for an IPv4
range naming another interface is 409, and so is a second IPv6 range (one IPv6
range can be masqueraded), a range already masqueraded, and the workload bridge
(400: it is not a way out of the node). An interface the server does not have is
404. A rule saved before these checks that is not honoured lists
not_enforced.
A range that overlaps the way the server is reached — its own network, its
gateway, its addresses, or another cluster member's address — is 409, whatever
interface it names: masquerade rewrites the source of every packet from the range
on each interface the server forwards on, including traffic arriving for the
server itself. Masquerade the workloads' own networks. A stored range like that is
not applied when the server starts, and lists not_enforced.
source and wan are accepted as aliases for source_cidr and interface,
matching the names the CLI uses. These are the same rules cenvero-str-ctl
gateway snat manages — both go through the same manager, so the two views
cannot drift.
curl -k "$NODE/api/v1/gateway/status" -H "Authorization: Bearer $TOKEN"
local_state is active or standby; peer_state is active, standby, or
solo (no peer configured). heartbeat is running, not running (a peer is
configured but cannot be heard, so the node never takes the VIP on its own), or
not needed (no peer):
{
"local_state": "active", "peer_state": "standby", "vip": "203.0.113.1",
"last_heartbeat": "2026-06-30T12:00:01Z", "uptime": "72h3m12s", "peer_addr": "10.0.0.6",
"heartbeat": "running"
}
curl -k -X POST "$NODE/api/v1/gateway/failover" -H "Authorization: Bearer $TOKEN"
{ "status": "failover_triggered" }
POST /api/v1/gateway/failback returns { "status": "failback_triggered" }.
Floating IPs
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/float | List floating IPs |
| POST | /api/v1/float | Assign a floating IP |
| GET | /api/v1/float/{id} | Get one floating IP |
| DELETE | /api/v1/float/{id} | Release a floating IP |
Assign a floating IP. ip is required: one address, with no prefix. A
floating address takes no primary or standby — whichever server holds it holds
it — so either is refused with 400, and an address saved with them before lists
them under not_enforced. state is active, standby, or failover.
An address that is no host's (unspecified, loopback, link-local, multicast or broadcast) is 400. One that is the server's default gateway, another cluster member's address, or an address the server already has is 409. A failover address your provider routes to the server on its own network is accepted. A server does not take on a saved floating address that has become one of these (when the agent starts, say), and its log says why.
curl -k -X POST "$NODE/api/v1/float" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"ip":"203.0.113.7"}'
{
"status": "created",
"floating_ip": { "id": "fip-7c1e", "ip": "203.0.113.7", "state": "active", "created_at": "2026-06-30T12:00:00Z" }
}
List:
{ "floating_ips": [ { "id": "fip-7c1e", "ip": "203.0.113.7", "active_host": "node-a", "state": "active", "created_at": "2026-06-30T12:00:00Z" } ] }
Release → DELETE /api/v1/float/fip-7c1e returns { "status": "deleted", "id": "fip-7c1e" }.
Floating IPs are saved on the node: they survive an agent restart or a reboot with the same ids, and the ones this node owns are brought back up on its interface when the agent starts.
Traffic visibility
Read-only views of live connections, usage accounting, and the bandwidth limits/quotas you have configured.
Flows
The live connection table the node tracks, plus aggregate stats and a downloadable export. All reads. With no traffic tracked these return empty results rather than erroring.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/flows | List flows (?state=new/active/closed) |
| GET | /api/v1/flows/stats | Aggregate statistics |
| GET | /api/v1/flows/export | Download flows (?format=csv/json, ?state=) |
curl -k "$NODE/api/v1/flows?state=active" -H "Authorization: Bearer $TOKEN"
{
"flows": [
{
"id": "f-001", "src_ip": "10.0.0.11", "dst_ip": "203.0.113.5", "src_port": 51000, "dst_port": 443, "protocol": "tcp",
"bytes_in": 12000, "bytes_out": 3400, "packets_in": 40, "packets_out": 28,
"start_time": "2026-06-30T11:59:00Z", "last_seen": "2026-06-30T12:00:00Z", "state": "active"
}
],
"count": 1
}
Stats (per_protocol/per_state are always present; top_talkers is ranked
by packet volume):
{
"stats": {
"total_flows": 128, "active_flows": 73, "total_bytes": 9120384, "total_packets": 21044,
"per_protocol": { "tcp": 110, "udp": 18 }, "per_state": { "active": 73, "closed": 55 },
"top_talkers": [ { "ip": "10.0.0.11", "packets": 8044, "bytes": 4011008, "flows": 12 } ]
}
}
Export streams a file (Content-Disposition: attachment). format defaults to
json; pass format=csv for a spreadsheet-friendly download:
curl -k "$NODE/api/v1/flows/export?format=csv&state=active" \
-H "Authorization: Bearer $TOKEN" -o flows.csv
Accounting
Per-period usage roll-ups derived from the node's traffic accounting. All three
accept an optional window via ?start= and ?end= (RFC 3339); the default window
is the current UTC calendar month to now.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/accounting/summary | Totals for the period |
| GET | /api/v1/accounting/billing | Per-source usage + cost (?rate= $/Mbps) |
| GET | /api/v1/accounting/95th | 95th-percentile in/out Mbps |
curl -k "$NODE/api/v1/accounting/summary" -H "Authorization: Bearer $TOKEN"
{
"summary": {
"total_bandwidth_gb": 12.5, "total_bytes": 12500000000, "total_packets": 9000000,
"total_vms": 4, "active_ips": 4, "period_start": "2026-06-01T00:00:00Z", "period_end": "2026-06-30T12:00:00Z"
}
}
Billing. rate is an optional $/Mbps figure for 95th-percentile billing; omit
it (or pass 0) to get per-source usage and P95 with zero cost.
curl -k "$NODE/api/v1/accounting/billing?rate=1.50" -H "Authorization: Bearer $TOKEN"
{
"billing": {
"period": "2026-06-01/2026-06-30", "total_usd": 42.00,
"items": [ { "mac": "aa:bb:cc:dd:ee:ff", "bytes_total": 8000000000, "gb": 8.0, "p95_mbps": 28.0, "cost_usd": 42.00 } ]
}
}
95th percentile:
{ "percentile_95th": { "in_mbps": 31.2, "out_mbps": 18.7, "period_start": "2026-06-01T00:00:00Z", "period_end": "2026-06-30T00:00:00Z" } }
Bandwidth limits, pools & quotas
Per-MAC rate limits, shared pools, and monthly usage quotas. *(Plan feature: Bandwidth shaping.)*
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/bandwidth | List limits + pools (or one limit via ?mac=) |
| POST | /api/v1/bandwidth | Create/update a per-MAC limit |
| POST | /api/v1/bandwidth/pools | Create a shared pool |
| POST | /api/v1/bandwidth/pools/members | Add a MAC to a pool |
| GET | /api/v1/bandwidth/quotas | List quotas (or one via ?mac=) |
| POST | /api/v1/bandwidth/quotas | Create/update a quota |
| GET | /api/v1/bandwidth/quotas/{mac} | Get one MAC's quota + status |
| DELETE | /api/v1/bandwidth/{id} | Remove a limit — that MAC becomes unshaped |
| DELETE | /api/v1/bandwidth/pools/{id} | Remove a shared pool |
| DELETE | /api/v1/bandwidth/pools/{id}/members/{mac} | Remove one MAC from a pool |
Several limits can name the same MAC (your own, a tenant's cap, a machine's cap): all of them hold, so the lowest rate in each direction applies. Removing a limit removes only that one; the MAC's other limits still hold, and with none left it draws whatever the node's licensed ceiling allows. Removing a pool, or one member from a pool, takes those MACs off the pool's rate in the same way. An unknown limit or pool is 404; removing a MAC that is not a member of an existing pool is 400.
curl -k -X DELETE "$NODE/api/v1/bandwidth/limit-1" -H "Authorization: Bearer $TOKEN"
curl -k -X DELETE "$NODE/api/v1/bandwidth/pools/1" -H "Authorization: Bearer $TOKEN"
curl -k -X DELETE "$NODE/api/v1/bandwidth/pools/1/members/aa:bb:cc:dd:ee:ff" \
-H "Authorization: Bearer $TOKEN"
Limit fields — id and target_mac (a MAC address, in any letter case) are
required. rate_bps is in bits per second and burst_bytes in bytes; a burst
left out is one second of the rate. direction is up, down, or both
(default both). pool_id links the limit to a shared pool. guaranteed_bps is
not available — a limit is a ceiling and nothing reserves a share — so a non-zero
value is 400; send 0 or leave it out. A limit saved earlier with a burst of
0 or a guaranteed_bps lists it under not_enforced.
curl -k -X POST "$NODE/api/v1/bandwidth" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"id":"vm-11-cap","target_mac":"aa:bb:cc:dd:ee:ff","rate_bps":1000000000,"burst_bytes":125000,"direction":"both"}'
{
"status": "updated",
"limit": { "id": "vm-11-cap", "target_mac": "aa:bb:cc:dd:ee:ff", "interface_id": 0, "rate_bps": 1000000000, "burst_bytes": 125000, "guaranteed_bps": 0, "direction": "both" }
}
List (returns all limits and pools; pass ?mac= to get a single limit, 404
if none). Note that pool objects use capitalized field names:
{
"limits": [ { "id": "vm-11-cap", "target_mac": "aa:bb:cc:dd:ee:ff", "interface_id": 0, "rate_bps": 1000000000, "burst_bytes": 125000, "guaranteed_bps": 0, "direction": "both" } ],
"pools": [ { "id": "tenant-a-pool", "name": "Tenant A shared", "total_bps": 10000000000, "allocated_bps": 2000000000, "members": ["aa:bb:cc:dd:ee:ff"] } ]
}
Create a shared pool — body: id and total_bps (both required), name
optional. Several MACs can then draw from the pool's aggregate cap.
curl -k -X POST "$NODE/api/v1/bandwidth/pools" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"id":"tenant-a-pool","name":"Tenant A shared","total_bps":10000000000}'
{ "status": "created", "id": "tenant-a-pool" }
Add a MAC to a pool — body: pool_id and member_mac (both required),
rate_bps optional: the member's own ceiling within the pool, with one second of
it as its burst. Adding a MAC that is already a member replaces its rate rather
than allocating it twice. A MAC is in one pool at a time. A rate that would take
the pool's allocations past its total_bps, a MAC that is in another pool, or a
member_mac that is not a MAC address, is 400; an unknown pool is 404.
curl -k -X POST "$NODE/api/v1/bandwidth/pools/members" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"pool_id":"tenant-a-pool","member_mac":"aa:bb:cc:dd:ee:ff","rate_bps":1000000000}'
{ "status": "added", "pool_id": "tenant-a-pool", "member_mac": "aa:bb:cc:dd:ee:ff" }
Quotas. A quota caps a MAC's monthly usage and resets at the start of each UTC
month. id, mac (any letter case) and monthly_limit_bytes (> 0) are
required. The quota counts the MAC's traffic whether or not the address has a
bandwidth limit, and its usage is brought up to date every few minutes. action
is notify (the default) or throttle, and enforced says what happens to the
address once it is over:
"enforced": truewith"action": "throttle"holds the address to almost nothing until the month resets or the quota is raised; its own limits apply again afterwards."enforced": false(the default) only alerts; nothing is limited.
An enforced quota whose action is not throttle is 400, and so is block, which
was the same as throttle. A quota saved earlier whose action does not say what it
does lists action under not_enforced.
curl -k -X POST "$NODE/api/v1/bandwidth/quotas" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"id":"q-vm11","mac":"aa:bb:cc:dd:ee:ff","monthly_limit_bytes":1000000000000,"action":"throttle","enforced":true}'
The response includes the derived status (ok, warning, exceeded),
remaining_bytes, and whether the MAC is currently throttled:
{
"status": "updated",
"quota": {
"id": "q-vm11", "mac": "aa:bb:cc:dd:ee:ff", "monthly_limit_bytes": 1000000000000, "used_bytes": 250000000000, "reset_day": 0,
"action": "throttle", "enforced": true, "current_period": "2026-06", "status": "ok", "remaining_bytes": 750000000000, "throttled": false
}
}
Get one MAC's quota: GET /api/v1/bandwidth/quotas/aa:bb:cc:dd:ee:ff returns
{ "quota": { ... } } with the same shape, or 404 { "error": "no quota for MAC ..." }.
GET /api/v1/bandwidth/quotas (no ?mac=) returns { "quotas": [ ... ] }.
Cluster
Form a cluster, add and remove members, and read the whole cluster from any
member (agent 1.0.0-rc.81 or later on every member). How a cluster works, what it
shares and what stays with a node is in the Clustering guide.
The /api/v1/cluster/… routes, reads included, need clustering in the licence
of the node you call, except five, which work whatever the licence says (below).
The reads of the cluster image library, placement, cluster networks and tenant usage
are never refused by the licence (see Images, placement, networks and usage).
A tenant key cannot use any of them (403). An account or API token needs
Cluster.Audit on /cluster to read them, and Cluster.Modify to change the
cluster (on /cluster/members to remove a member, leave or rekey).
(Plan feature: Cluster — every member needs its own licence that includes it.)
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/cluster | Cluster summary |
| GET | /api/v1/cluster/status | State, leader, voters and members |
| GET | /api/v1/cluster/state | Counts of the shared settings |
| POST | /api/v1/cluster/create | Form a cluster with this node as its first member (a task) |
| POST | /api/v1/cluster/join-codes | Make a join code |
| GET | /api/v1/cluster/join-codes | List the join codes (never the codes themselves) |
| DELETE | /api/v1/cluster/join-codes/{id} | Revoke a join code that has not been used |
| POST | /api/v1/cluster/join-preview | Ask the cluster what joining it would mean, changing nothing (on the node that would join) |
| POST | /api/v1/cluster/join-with-code | Join this node to a cluster (a task) |
| DELETE | /api/v1/cluster/members/{id} | Take a member out of the cluster, from any member |
| POST | /api/v1/cluster/leave | Take this node out of its cluster |
| POST | /api/v1/cluster/members/{id}/rekey | Give a member a new identity (a task) |
| POST | /api/v1/cluster/ca/rotate | Replace the cluster's certificate authority (a task) |
| GET | /api/v1/cluster/resources | Every object of every member (see Working with other members) |
| GET | /api/v1/cluster/tasks | Every member's tasks |
| GET | /api/v1/cluster/audit | Every member's audit records |
| GET | /api/v1/cluster/events | Every member's events, as one stream |
| POST | /api/v1/cluster/join | Only for a cluster set up by hand with an earlier version (see below) |
| GET | /api/v1/cluster/images | The cluster image library: each image, its copies and the machines that use it |
| POST | /api/v1/cluster/images | Add an image to the library, from an address or the catalogue (a 202 with the task) |
| GET | /api/v1/cluster/images/{id} | One library entry |
| POST | /api/v1/cluster/images/{id}/placements | Copy an image to a member (a task) |
| DELETE | /api/v1/cluster/images/{id}/placements/{node} | Remove a member's copy of an image |
| DELETE | /api/v1/cluster/images/{id} | Remove an image from the library |
| POST | /api/v1/images/{id}/publish | Publish a member's image to the library, with the same id |
| GET | /api/v1/cluster/placement | Every member's answer for a machine of a given size, with its reasons |
| GET | /api/v1/cluster/networks | The cluster networks, and whether they are released for machines |
| POST | /api/v1/cluster/networks | Create a cluster network |
| GET | /api/v1/cluster/networks/{id} | One cluster network, with the same released flag |
| PUT | /api/v1/cluster/networks/{id}/host-gateway | Set or clear the member that runs a network's host gateway; "dhcp": false with the host gateway is refused |
| DELETE | /api/v1/cluster/networks/{id} | Delete a cluster network that no machine is attached to |
| GET | /api/v1/cluster/tenants/{id}/usage | A tenant's machines and volumes across the cluster |
| POST | /api/v1/vms/{id}/migrate | Move a machine to another member, stopped and copied, or while it runs with "mode": "live" (a 202 with the task and the move) |
| GET | /api/v1/migrations/{id} | One move, with its steps |
| GET | /api/v1/vms/{id}/migrations | A machine's moves, newest first |
| POST | /api/v1/migrations/{id}/cancel | Cancel a move until its commit (a live move only until its switch) |
| POST | /api/v1/migrations/{id}/decide | Decide a move whose member was lost during its switch, its release or its start (a 200 with the move) |
| POST | /api/v1/cluster/migrations | Move several machines in one task, each judged before any moves (a 202 with the task) |
| GET | /api/v1/nodes/{node}/maintenance | A member's maintenance |
| PUT | /api/v1/nodes/{node}/maintenance | Put a member into maintenance, or end it; with evacuate, move its machines off first (a 202 with the task) |
| GET | /api/v1/nodes/{node}/evacuation-plan | Where each machine of a member would move, or why it stays |
| GET | /api/v1/options/cluster-compute | The cluster's settings for moves and placement (Cluster compute settings) |
| PUT | /api/v1/options/cluster-compute | Change the cluster's settings for moves and placement |
Five routes work whatever the licence says: without clustering in it, and while it is frozen. So a member whose plan lost clustering can still see where it stands and withdraw a code, and a node can always be taken out:
| Route | Command line |
|---|---|
GET /api/v1/cluster/status | cluster status |
GET /api/v1/cluster/join-codes | cluster join-code list |
DELETE /api/v1/cluster/join-codes/{id} | cluster join-code revoke <id> |
DELETE /api/v1/cluster/members/{id} | cluster remove <node-id> |
POST /api/v1/cluster/leave | cluster leave |
Every other cluster route needs clustering in the licence: the summary
(GET /api/v1/cluster), /cluster/state, the cluster-wide views (resources,
tasks, audit and events), and every route that forms, joins or changes the
cluster. The join preview, which changes nothing, also works while the licence
is frozen; the other changes follow the licence state as any
change does. A change only the cluster's leader can make — a removal, a join
code, a rotation — is passed to the leader by the member you call, so you can
call any member.
Status
curl -k "$NODE/api/v1/cluster/status" -H "Authorization: Bearer $TOKEN"
{
"enabled": true,
"state": "leader",
"leader": "10.0.0.5:7073",
"is_leader": true,
"cluster": { "id": "0f1e2d3c4b5a69788796a5b4c3d2e1f0", "name": "prod" },
"voters": 1,
"peers": [
{ "id": "3f2a0c1e-9b7d-4c1a-8e2f-0123456789ab", "address": "10.0.0.5:7073", "state": "leader",
"name": "edge-1", "voter": true, "pinned": true, "online": true },
{ "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "address": "10.0.0.6:7073", "state": "non-voter",
"name": "edge-2", "voter": false, "pinned": true, "online": true, "last_seen": "2026-09-30T11:59:58Z" }
]
}
| Field | Meaning |
|---|---|
enabled | Whether this node is in a cluster |
state | This node's role: leader, follower, or candidate (an election is under way). disabled on a node that is not in a cluster, not running when it is in one but its clustering could not start (the agent log says why) |
leader | The leader's cluster address; empty when there is none |
is_leader | Whether this node is the leader |
cluster | The cluster's id and name |
voters | How many members vote |
peers | Every member, this node included: id (what the other routes name a node by), name, address (its cluster address), state (leader, follower, or non-voter), voter, pinned (the cluster has recorded its identity), online, and last_seen for the others |
error | Only on a member that is not taking part in its cluster, saying why in a sentence (see A member that is not taking part); absent otherwise |
GET /api/v1/cluster reports the same, wrapped as { "cluster": { … } }, where
the member list is called members. A node that is not in a cluster answers
state disabled with an empty list.
A member that is not taking part
A member keeps running on its own, with changes to shared settings paused on
it, in two cases; error says which.
Its clustering could not start when the agent started. state is
not running, and error reads:
clustering could not start on this node; it keeps running on its own, and changes to shared settings are paused until clustering starts; the agent log has the reason
It reaches no leader, and none of the members it knows answers when it asks
them which members the cluster has now. (A member that was switched off asks
them as it starts, so that it learns which nodes joined or were removed while
it was away.) error then reads:
this node reaches no leader of its cluster, and none of the members it knows answered when it asked which members the cluster has now; it keeps running on its own and changes to shared settings are paused until it reaches the cluster; the agent log has the reason
In both cases the same sentence is the reason of the node's own entry in
GET /api/v1/nodes.
Images, placement, networks and usage across the cluster
These routes work across the members of a cluster, and each needs every member to run a version that supports it. Until every member runs a version that supports it, a route answers 409 with "Every member must run a version that supports this."; on a node in no cluster it answers 409 with "This needs a cluster of servers: create one or join one first." A tenant key cannot use them (403).
- Library.
POST /api/v1/cluster/imagestakes{"name", "node", "url", "sha256"}or{"name", "node", "catalogue"}, names the member that brings the image in, and answers 202 with the image'sidand itstask. A name another image holds is 409.GET /api/v1/cluster/imagesanswers{"images": [...]}: each entry has itsplacements, one for each member that holds a copy (stateverified), andreferenced_by, the number of machines that use it. - Copies and removal.
POST /api/v1/cluster/images/{id}/placementswith{"node"}answers 202 with a task. The twoDELETEroutes answer 200. Each is 409 while a machine uses the image, and the answer names the machines. - Publish.
POST /api/v1/images/{id}/publishanswers 200 with the library entry. The image must be ready and its checksum verified. - Placement.
GET /api/v1/cluster/placementanswers 200 withrequestandcandidates: one entry for each member, witheligible,rank(nullwhen the member is not eligible) andreasons.POST /api/v1/vmstakes"placement": "auto"or"node": "<member id>", not both. When no member can take the machine it answers 409 with the reasons of each member. See Placing machines. - Networks.
POST /api/v1/cluster/networkstakes{"name", "cidr", "gateway", "tenant_id", "mtu", "host_gateway", "dhcp"}and answers 202 with the network (withhost_gateway_errorwhen the network was created and its host gateway was not set).PUT …/host-gatewaytakes{"node", "enabled"}and answers 202. TheDELETEanswers 200, or 409 while a machine is attached. The list answers{"networks": [...], "released": false}, and each network's own answer carries the samereleasedflag. While it isfalse, no network can take a machine, and each network'sstateisawaiting_check; it readsreadyonce it is released. See Cluster networks. - Usage.
GET /api/v1/cluster/tenants/{id}/usageanswers{"tenant_id", "vms": {"used", "max"}, "volumes": {"used", "max"}, "per_member": [{"node", "vms", "volumes", "bytes"}]}.maxisnullwhere the tenant has no limit.bytesisnullin this release, because the cluster does not yet record each volume's size. A tenant this node does not hold answers 404 (tenant: <id> not found), as a tenant you may not see does.
Moving machines, maintenance and evacuation
These routes work across the members of a cluster, and each needs every member to run a version that supports it. Until then they answer 409 with "Every member must run a version that supports this."; on a node in no cluster, 409 with "This needs a cluster of servers: create one or join one first." A tenant key cannot use them (403). Reads are never refused by the licence.
| Method | Path | Privilege | Licence | Answers |
|---|---|---|---|---|
| POST | /api/v1/vms/{id}/migrate | VM.Migrate on the machine | compute | 202 with task and migration |
| GET | /api/v1/migrations/{id} | VM.Audit on the machine | none | 200 with migration |
| GET | /api/v1/vms/{id}/migrations | VM.Audit on the machine | none | 200 with migrations, newest first |
| POST | /api/v1/migrations/{id}/cancel | VM.Migrate on the machine | compute; never refused by the freeze | 200 with migration, or 409 after the commit |
| POST | /api/v1/migrations/{id}/decide | Cluster.Modify on the cluster | compute; never refused by the freeze | 200 with migration; 409 with the sentence that refuses it; 503 while the member cannot read the machine or record the decision |
| POST | /api/v1/cluster/migrations | VM.Migrate on each machine | compute | 202 with task, or 409 naming each machine that cannot move |
| GET | /api/v1/nodes/{node}/maintenance | Cluster.Audit on the member | none | 200 |
| PUT | /api/v1/nodes/{node}/maintenance | Cluster.Modify on the member | cluster; ending is never refused by the freeze | 200; with evacuate, 202 with the run's task |
| GET | /api/v1/nodes/{node}/evacuation-plan | Cluster.Audit on the member | none | 200 |
| GET | /api/v1/options/cluster-compute | Cluster.Audit on the cluster | none | 200 |
| PUT | /api/v1/options/cluster-compute | Cluster.Modify on the cluster | compute; a frozen licence refuses it | 200 with the settings |
Moving a machine. POST /api/v1/vms/{id}/migrate takes {"node": "<member id>"} or {"node": "auto"}, and an optional "mode". The mode is auto (the default) or offline, which stop, move and start the machine, or live, which moves it while it runs (Moving machines between nodes). A body that names no member, or a mode that is none of these, is refused with 400 and the sentence that says why. Add ?check=1 to judge the move without starting it: the answer is 200 with {"check": "ok"} when the checks the member makes pass, or 409 with the sentence that refuses it. For a live move, the new member judges a named processor itself when the move starts, so a dry run can answer ok and the move still end with the processor sentence. The member id is the one cluster status lists. You can call any member: when another member holds the machine, it passes the request on.
curl -k "$NODE/api/v1/vms/vm-3f9a1c2e/migrate" -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" -d '{"node": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "mode": "offline"}'
The answer is 202, with the task that records the move and the move itself:
{
"task": "tsk-3f2a0c1e9b7d-0mumq7fmz-a05dee",
"migration": {
"id": "mig-3f9a1c2e5b7d4a10",
"machine_id": "vm-3f9a1c2e",
"from": "3f2a0c1e-9b7d-4c1a-8e2f-0123456789ab",
"to": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"mode": "offline",
"phase": "prepare",
"reason": "",
"cancellable": true,
"started_at": "2026-10-24T09:14:02Z",
"updated_at": "2026-10-24T09:14:02Z",
"steps": [
{"name": "prepare", "state": "running", "bytes_done": 0, "bytes_total": 0},
{"name": "copy", "state": "pending", "bytes_done": 0, "bytes_total": 0},
{"name": "commit", "state": "pending", "bytes_done": 0, "bytes_total": 0},
{"name": "starting", "state": "pending", "bytes_done": 0, "bytes_total": 0},
{"name": "start", "state": "pending", "bytes_done": 0, "bytes_total": 0},
{"name": "cleanup", "state": "pending", "bytes_done": 0, "bytes_total": 0}
]
}
}
A move's phase is prepare, copy, commit, starting or start while it runs, and done, failed or cancelled when it has ended. A move while running, whose mode is live, goes from prepare to switching, where its memory is carried while the machine runs, and then to released, where the old member's copy is gone and the machine waits paused on the new member. Its steps keep the same names, and its copy step is the transfer. cancellable is true in prepare, and in copy for a stop, move and start move; it is false from switching on. reason is the sentence a move that failed or was cancelled ended with, and steps gives each step's state (pending, running, done or failed) and, during the copy, its bytes. A move's answer carries no path, no token and no address of another tenant. A move that is refused answers 409 with error, the sentence. For a named member, or for auto, it also gives the placement answer's request and candidates, so each member's reasons are listed. See Moving machines between nodes for every sentence.
Following and cancelling. GET /api/v1/migrations/{id} returns one move, and GET /api/v1/vms/{id}/migrations the moves of a machine from the last 30 days, newest first. POST /api/v1/migrations/{id}/cancel ends a move before its commit and answers 200 with the move. After the commit it answers 409 with "The move has passed its commit and cannot be cancelled. It will finish, or the owner will be set back while the source still has its files." A move while running cannot be cancelled from its switch on, and its cancel answers 409 with "This move cannot be cancelled from this member right now. Try again shortly."
Deciding a lost member. POST /api/v1/migrations/{id}/decide takes {"lost": "<member id>", "owner": "<member id>"}, with "source_down": true when the lost member is the old member, and needs Cluster.Modify on the cluster. The member that takes the machine makes the decision, and a request that reaches the other member is passed on to it. A lost new member is decided with the owner set to the old member, once the move is released. A lost old member is decided with the owner set to the new member and "source_down": true, which confirms that the old member is down. The same decision ends a move whose new member has already started the machine. The answer is 200 with the move. The sentences that refuse a decision are listed in Moving machines between nodes.
Maintenance. PUT /api/v1/nodes/{node}/maintenance takes {"enabled": true} or {"enabled": false}. enabled is required. evacuate is accepted with enabled: true only. With it the member goes into maintenance, and the answer is 202 with the evacuation's task; mode is auto, the default, or offline, and live is not available yet. A member in maintenance takes no machine, and nothing moves onto it. Its machines keep running.
{"node": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "enabled": true, "since": "2026-10-24T09:20:00Z", "evacuation": null}
GET /api/v1/nodes/{node}/maintenance answers the same shape, and evacuation is null while no evacuation run has started on that member.
The evacuation plan. GET /api/v1/nodes/{node}/evacuation-plan changes nothing. It lists the member's machines largest first, by memory and then by machine id, with planned_count, skipped_count and, for each machine, the member it would move to (planned) or the sentences that say why it stays (skipped and reasons). The reasons are described on Maintenance and evacuation. The plan answers 503 while the member's machines cannot be read.
Several machines at once. POST /api/v1/cluster/migrations takes {"vms": ["vm-3f9a1c2e", "vm-7d4e2f10"], "node": "<member id>" or "auto", "mode": "offline"}, for 1 to 100 machines, each named once. It judges every machine before any moves; if one cannot move, nothing moves and the answer is 409 with the sentence "No machine was moved, because some of the machines cannot move. The reasons are listed for each machine." and refused, a list of {"vm", "reason"}. A request that passes that check answers 202 with the run's task. A machine another member holds is refused with "This machine is on another member. Run the command on that member, with --node set to it." (the console sends each owner its own machines). A bulk move moves its machines stopped: a "mode": "live" is refused for each machine with "Moving a running machine is not available yet. Choose an offline move.", so the answer is 409 and nothing moves.
Cluster compute settings
The settings every member of a cluster shares for moves and placement. GET /api/v1/options/cluster-compute reads them, and needs Cluster.Audit on the cluster. PUT /api/v1/options/cluster-compute changes them, and needs Cluster.Modify on the cluster and Compute in the licence; a frozen licence refuses it. A read is never refused by the licence. Until every member runs a version that supports them, the settings answer the defaults, and a change answers 409.
| Setting | Allowed | Default | What it does |
|---|---|---|---|
migration_bandwidth_mib_s | 1 to 4096 | 256 | The speed a move's copy keeps to, in MiB per second |
migration_concurrency | 1 or 2 | 1 | How many machines an evacuation or a bulk move moves at once |
overcommit_vcpu | 1 to 16 | 4 | How many virtual CPUs a member may commit for each CPU it has, for placement |
cluster_cpu_policy | baseline or host | baseline | baseline gives a new machine in a cluster the cluster's named processor model, so that it can move between members; host gives it the host's own processor model |
network_mtu_default | 576 to 9000 | 1500 | The default MTU of the guests on a cluster network, within what each member's network can carry |
rev | — | — | The setting's revision. Send back the one you read |
{"migration_bandwidth_mib_s": 256, "migration_concurrency": 1, "overcommit_vcpu": 4, "cluster_cpu_policy": "baseline", "network_mtu_default": 1500, "rev": 0}
PUT takes the whole object, with the rev you read. A value outside its range answers 400 and names the setting, for example: "This cluster compute setting is outside its allowed range: migration_concurrency." A rev that is no longer the current one answers 409 with "These settings changed since you read them. Read them again, then set them." Until every member runs a version that supports them, a change answers 409 with "Every member must run a version that supports this."
Form a cluster
curl -k -X POST "$NODE/api/v1/cluster/create" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name":"prod","bind_addr":"10.0.0.5"}'
202, with the task that does the work and a Location header
naming it:
{ "task": "tsk-3f2a0c1e9b7d-0mumq7fmz-a05dee", "cluster": { "id": "0f1e2d3c4b5a69788796a5b4c3d2e1f0", "name": "prod" } }
name is up to 64 bytes: 64 characters of unaccented letters, digits and
punctuation, fewer with accented letters or other scripts, which take two to
four bytes per character. bind_addr is an address of this node, as
10.0.0.5 or 10.0.0.5:7073: not a wildcard, and always on port 7073; anything
else is 400. A node that is already a member of a cluster, or still holds an
earlier cluster's data, is 409 with what to do.
Join codes
curl -k -X POST "$NODE/api/v1/cluster/join-codes" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"expires_in":"30m"}'
201 — the only answer that ever carries the code:
{ "id": "9f86d081884c7d65", "code": "STRJ1-AQ8eLTxLWml4h5altMPS4fCgoaKjpKWmp6ipqqus…", "expires_at": "2026-09-30T12:15:00Z" }
expires_in is a number of seconds or a duration such as "15m": from 60
seconds to 24 hours, 15 minutes when left out. A code works once. A cluster
holds at most 20 active codes (made, and not yet used, revoked or expired);
revoke one to make room.
GET /api/v1/cluster/join-codes lists them without the codes:
{
"join_codes": [
{ "id": "9f86d081884c7d65", "created_by": "api key ak-1f2e", "created_at": "2026-09-30T12:00:00Z",
"expires_at": "2026-09-30T12:15:00Z", "state": "active", "used_by": "", "used_at": null },
{ "id": "0d1e2f3a4b5c6d7e", "created_by": "root", "created_at": "2026-09-30T09:00:00Z",
"expires_at": "2026-09-30T09:15:00Z", "state": "used",
"used_by": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "used_at": "2026-09-30T09:03:12Z" }
]
}
state is active, used, revoked or expired.
DELETE /api/v1/cluster/join-codes/{id} revokes an unused one and answers
{ "id": "9f86d081884c7d65", "state": "revoked" }.
Join a cluster
First, if you like, the preview. On the new node, ask the cluster what joining it would mean. Nothing changes anywhere and the code is not used up:
curl -k -X POST "$NODE/api/v1/cluster/join-preview" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"code":"STRJ1-…","adopt_cluster_tenants":false}'
{
"cluster": { "id": "0f1e2d3c4b5a69788796a5b4c3d2e1f0", "name": "prod" },
"members": 2,
"tenants": {
"shared": [ { "id": "t-beta", "name": "Beta" } ],
"merged": [ { "id": "t-gamma", "name": "Gamma" } ]
},
"conflicts": [
{ "type": "tenant", "id": "t-acme", "local_name": "acme", "cluster_name": "Acme Corp" },
{ "type": "allocation", "id": "7:10.20.0.5", "local_name": "vm-1a2b3c4d", "cluster_name": "vm-9f8e7d6c" }
]
}
| Field | Meaning |
|---|---|
cluster | The cluster's id and name (the code itself carries only the id) |
members | How many nodes it has |
tenants.shared | This node's tenants the cluster does not have yet: they become the cluster's |
tenants.merged | This node's tenants the cluster already has (the same id and name, or the same id with adopt_cluster_tenants): the cluster's record wins |
conflicts | What would stop the join, as in the join's 409 below |
options_given_up | Only when there are any: this node's own settings that the join gives up, because the cluster's replace them — "brand", "notifications", "tag_colours" |
floating_given_up | Only when there are any: this node's own floating addresses that the cluster holds for another member. The join gives them up, and the cluster keeps them — a list of addresses such as "203.0.113.20" |
The preview is refused exactly as the join would refuse the same code (wrong, expired, used, revoked, a full cluster, a node already in a cluster), so it tells you nothing a join with the code would not. Like a join, it counts toward the cluster's limit on join attempts.
Then the join, on the new node, with a code made on any member:
curl -k -X POST "$NODE/api/v1/cluster/join-with-code" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"code":"STRJ1-…","bind_addr":"10.0.0.6","adopt_cluster_tenants":false}'
202 { "task": "tsk-…" }: the node was admitted, and the task finishes the
join. When the node's records clash with the cluster's, nothing is joined and the
answer is 409 with each conflict:
{
"error": "this node's records conflict with the cluster's (listed in conflicts); resolve them, or join with adopt_cluster_tenants to let the cluster's tenants win",
"conflicts": [
{ "type": "tenant", "id": "t-acme", "local_name": "acme", "cluster_name": "Acme Corp" },
{ "type": "allocation", "id": "7:10.20.0.5", "local_name": "vm-1a2b3c4d", "cluster_name": "vm-9f8e7d6c" }
]
}
A tenant conflict means the same id with another name: set
adopt_cluster_tenants to true to let the cluster's record win. An address
allocated to different owners has to be resolved before joining.
A code that is wrong, or another cluster's, is 403
the join code was not accepted; an expired, used or revoked one is 409
this join code has expired, this join code has already been used or
this join code was revoked; a full cluster is 409
this cluster has 32 nodes, the most it supports.
Remove a member, or leave
curl -k -X DELETE "$NODE/api/v1/cluster/members/7c9e6679-7425-40de-944b-e07fc1f90ae7" \
-H "Authorization: Bearer $TOKEN"
{ "status": "removed", "node_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" }
The member is refused by the others from that moment. If the voting members
cannot agree to the removal, the answer is 503
removal pending: the cluster could not agree; the node can no longer reach the others
and the member stays cut off. An id that is not a member is 404.
POST /api/v1/cluster/leave takes the node you call out of its cluster and
answers { "status": "left" }; it becomes a standalone node. On a member that
is not the leader, the node asks the leader to take it out and answers once it
is standalone. If the leader's answer is lost and the node has not seen itself
removed, the answer is 503:
{ "error": "the cluster's leader did not answer, and this node has not seen itself removed: if `cluster status` on another member still lists this node, run the leave again; if it does not, run `cenvero-str-ctl cluster forget --yes` here" }
A removal that names the node you call is a leave, and can answer the same 503. Removing and leaving work whatever the licence says (see Cluster).
Membership events
Every member announces each change of the cluster's membership on its own
event stream, as the event
cluster.membership in the CLUSTER category, one event per node that changed.
Its type, category, object and payload (the other fields are those of every
event):
{ "type": "cluster.membership", "category": "CLUSTER", "object": "/cluster/members/7c9e6679-7425-40de-944b-e07fc1f90ae7",
"payload": { "node": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "name": "edge-2", "change": "promoted", "voter": true } }
change is admitted (a join code was accepted; the node has not finished
joining), joined (it is a member, perhaps without a vote yet), promoted (it
votes), demoted (it no longer votes) or removed (it was removed or left, or
its join never finished). voter is whether it votes now. A node that leaves,
is removed or forgets its cluster announces its own removal. A member that
restarts does not announce again what happened before it stopped: read
GET /api/v1/nodes afresh instead.
Identities and the certificate authority
POST /api/v1/cluster/members/{id}/rekey gives member {id} a new identity
(local names the node you call), and POST /api/v1/cluster/ca/rotate replaces
the cluster's certificate authority, the members keeping their identities. Both
answer 202 { "task": "tsk-…" }. Each member's identity, and when it expires,
is in GET /api/v1/nodes (cert_expires_at).
Shared settings and a node that cannot reach the leader
GET /api/v1/cluster/state counts the shared settings:
{ "blocklist_count": 0, "ip_allocations_count": 12, "vxlan_peers_count": 2, "floating_ips_count": 1, "tenants_count": 3 }
On a member that cannot reach the cluster's leader — the smaller side of a
network split, or a node cut off from the others — changes to tenants and
overlay peers are refused with 503 and nothing changes on the node: creating,
updating, suspending, resuming or limiting a tenant, setting its quota where
that changes max_bandwidth_bps, deleting it (the /tenant and
/billing/tenants routes), and adding or removing a VXLAN peer. Such a change
has to reach the cluster as a whole, so that every member applies the same one.
(A tenant's other quotas belong to each node, and can still be changed there.)
The answer:
{ "error": "the cluster has no leader reachable from this node; changes to shared settings are paused until it has one" }
Make the change on a member that can reach the others, or restore the network between the members. Reads keep working. See A node cut off from the others.
Deleting a tenant on a cluster deletes it, and revokes its tenant API keys, on
every member. It is refused with 409 while a member still holds the tenant's
machines, networks or volumes
(tenant <id> still has machines, networks or volumes on node <name>) or cannot
be asked (node <name> is not answering, so its resources cannot be checked).
A cluster set up by hand
POST /api/v1/cluster/join (node_id, address), on the leader, adds a member
to a cluster set up by hand with an earlier version, before join codes existed.
A cluster formed with join codes answers 409 add nodes with a join code.
POST /api/v1/cluster/profile answers 501: node profiles were removed, and
every node runs the same services.
Access control
Accounts, groups, roles, permissions, API tokens, sign-in methods and second factors, and what the caller may do. How they work — paths, roles, second factors, identity providers — is in Accounts and Access Control; this is the reference.
- Every route is under
/api/v1/access/. None is a licence feature, and no change here is ever frozen by the licence. - A tenant key reaches none of them (403).
- An object the caller may not see — an account, group, sign-in method, permission or token — answers exactly as an address the API does not serve (404), and a list holds only what the caller may see.
- Every object carries
rev. Send it back asif_rev(in the body, or?if_rev=on a delete) and a change made since is refused with 409this account changed since you loaded it; reload and try again. - In a cluster these settings belong to the whole cluster: call
/api/v1/access/…on any member. They are on once every member runs this release; until then every route answers 409access control is available once every node of this cluster runs version <v>; <n> nodes still need the update. A change on a member that cannot reach the others answers 503, as other shared settings do.
| Method | Path | Who may call it | Answer |
|---|---|---|---|
| GET | /api/v1/access/me | Anyone signed in | Who you are, your account, the roles you hold and where, and your session |
| GET | /api/v1/access/permissions | Anyone signed in | What you may do: ?path=P, ?paths=P1,P2,… (up to 100), or every path you hold a role on |
| GET | /api/v1/access/privileges | Anyone signed in | Every privilege, with what it allows |
| GET | /api/v1/access/roles, /api/v1/access/roles/{id} | Anyone signed in | Roles and their privileges |
| POST | /api/v1/access/roles | Access.Modify on /access | Create a custom role: {"id","privileges":[…],"tfa_required"} (201) |
| PUT, DELETE | /api/v1/access/roles/{id} | Access.Modify on /access | Change or delete a custom role (a built-in one: 409 built-in roles cannot be changed) |
| GET | /api/v1/access/users, /api/v1/access/users/{id} | Access.Audit on the account; yourself | Accounts |
| POST | /api/v1/access/users | Access.Modify on /access/users | Create an account: {"id","display_name","email","enabled","expires_at","groups","tfa_required"} (201) |
| PUT | /api/v1/access/users/{id} | Access.Modify; yourself for display_name and email | Change an account (only the fields you send) |
| DELETE | /api/v1/access/users/{id} | Access.Modify | Delete an account with its tokens, second factor and permissions |
| PUT | /api/v1/access/users/{id}/password | Access.Modify; yourself | Set a Stratum account's password: {"password"}. Answers {"id","password_changed_at","sessions_ended":true} |
| GET | /api/v1/access/users/{id}/tfa | Access.Audit; yourself | Whether it must use a second factor, and what it has set up |
| POST | /api/v1/access/users/{id}/tfa/totp, /api/v1/access/users/{id}/tfa/totp/confirm | Yourself only | Set up an authenticator app, then confirm it with a code: {"enrolment_id","code"} |
| POST | /api/v1/access/users/{id}/tfa/recovery | Yourself only | New recovery codes (the old ones stop working) |
| DELETE | /api/v1/access/users/{id}/tfa | Access.Modify; yourself | Remove its authenticator and recovery codes. Answers {"id","tfa_removed":true,"sessions_ended":true} |
| GET | /api/v1/access/users/{id}/tokens | Access.Audit; yourself with Access.Token | An account's API tokens |
| POST | /api/v1/access/users/{id}/tokens | Access.Modify; yourself with Access.Token | Make a token: {"name","comment","privsep","expires_at"} (201, with the secret, shown once) |
| DELETE | /api/v1/access/users/{id}/tokens/{name} | Access.Modify; yourself | Revoke a token for good |
| GET | /api/v1/access/tokens | Access.Audit | Every API token, the operator keys among them |
| GET | /api/v1/access/groups, /api/v1/access/groups/{id} | Access.Audit | Groups and their members |
| POST, PUT, DELETE | /api/v1/access/groups, /api/v1/access/groups/{id} | Access.Modify | Create ({"id","comment","members"}), change (members replaces the list), delete |
| GET | /api/v1/access/acl | Paths where you have Access.Audit, and your own | Permissions, filtered by path, subject_type and subject |
| POST | /api/v1/access/acl | Access.Modify on the path, and every privilege of the role there; yourself for your own tokens | Give a role: {"path","subject":{"type","id"},"role","propagate"} (201) |
| DELETE | /api/v1/access/acl/{id} | Access.Modify on the path; yourself for your own tokens | Remove a permission |
| GET | /api/v1/access/realms, /api/v1/access/realms/{id} | Access.Audit | Sign-in methods |
| POST, PUT, DELETE | /api/v1/access/realms, /api/v1/access/realms/{id} | Access.Modify | Add, change or delete a sign-in method (local cannot be deleted) |
| POST | /api/v1/access/realms/{id}/test | Access.Modify | Check an identity provider's settings and signing keys, changing nothing |
subject.type is user, group or token. "Yourself" needs no privilege.
Sessions end with the credential. "sessions_ended": true in the answer to
a password change (PUT /api/v1/access/users/{id}/password) or to removing a
second factor (DELETE /api/v1/access/users/{id}/tfa) says that every session
of the account that signed in before the change has ended, on every server. A
person who changed their own in the web console carries on in a renewed session.
Setting up a new authenticator ends the account's other sessions the same way.
Changes that need the password again. Changing any password; setting up,
removing or resetting a second factor and making new recovery codes; giving
Administrator or a role with Access.Modify, or adding members to a group that
holds one; giving a custom role Access.Modify, or deleting one that has it;
making a token with "privsep": false; every change to a sign-in method;
changing the brand (its settings, logo or favicon) or the notification settings;
deleting any account, and disabling one that holds Administrator. So does a
change that gives someone back Access.Modify by taking something away —
removing a permission (DELETE /api/v1/access/acl/{id}), a group
(DELETE /api/v1/access/groups/{id}), a group's member, or a custom role
(DELETE /api/v1/access/roles/{id}) that kept it from them — or that brings
back an account holding it (enabled again, or its expiry removed or moved
later), and one that stops requiring a second factor of an account or a custom
role. They are accepted from a person in the web console who confirmed within
five minutes, and from the node API token on its own node. Anything else is
refused with 403: an API token or operator key with
an API token cannot make this change; sign in to the web console to make it,
an unconfirmed console session with confirm your password to make this change
and "reauth_required": true. Setting up a second factor is therefore done in
the web console. Revoking a token never needs it, nor does any other way of
taking power away that this list does not name.
Who you are, and what you may do
curl -k "$NODE/api/v1/access/me" -H "Authorization: Bearer $TOKEN"
For a person signed in to the web console, the answer looks like this:
{
"principal": { "kind": "user", "id": "alice@local", "name": "alice@local", "realm": "local" },
"user": { "id": "alice@local", "realm": "local", "name": "alice", "display_name": "Alice", "enabled": true,
"groups": ["ops"], "tfa_required": false, "tfa": { "totp": true, "recovery_codes_left": 9 } },
"roles": [ { "path": "/", "role": "Administrator", "via": "group ops", "propagate": true } ],
"session": { "auth_method": "password+totp", "signed_in_at": "2026-10-03T10:04:12Z", "sudo_until": "2026-10-03T10:09:12Z" },
"bootstrap": false,
"identity_stale": false
}
via says how a role is held: direct, group <id>, token or built-in.
sudo_until is when a confirmation of the password stops counting. bootstrap
is true for the node API token. identity_stale is true on a cluster member
that cannot reach the others, whose access settings may be behind (see
In a cluster).
curl -k "$NODE/api/v1/access/permissions?paths=/vms/vm-1a2b3c4d,/tenants/t-globex" -H "Authorization: Bearer $TOKEN"
{
"principal": { "kind": "user", "id": "alice@local", "name": "alice@local" },
"permissions": {
"/vms/vm-1a2b3c4d": ["VM.Audit", "VM.Console", "VM.GuestAgent", "VM.PowerMgmt"],
"/tenants/t-globex": []
},
"sudo_until": null
}
An object you may not see answers as one with no privileges. In a cluster, ask
the member that holds an object about it:
/api/v1/nodes/<node id>/access/permissions?paths=…. That is the only access
route that can be reached through another member; any other
/api/v1/nodes/<node id>/access/… answers 400
access settings are answered by whichever node you ask; call /api/v1/access/… directly.
Accounts, permissions and tokens
# An account, its password, and a role on one tenant
curl -k -X POST "$NODE/api/v1/access/users" -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" -d '{"id":"bob@local","display_name":"Bob"}'
curl -k -X PUT "$NODE/api/v1/access/users/bob@local/password" -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" -d "{\"password\":\"$BOB_PASSWORD\"}"
curl -k -X POST "$NODE/api/v1/access/acl" -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"path":"/tenants/t-acme","subject":{"type":"user","id":"bob@local"},"role":"Support","propagate":true}'
{ "id": "acl-1f3a9c0d2b4e5f60", "path": "/tenants/t-acme", "subject": { "type": "user", "id": "bob@local" },
"role": "Support", "propagate": true, "rev": 1 }
A permission's id is the same for the same path, subject and role, so giving the
same role twice changes nothing. Giving a role with privileges you do not hold
on the path is refused with 409
you cannot grant a role with privileges you do not hold on <path>.
# A token for a script, with only what it needs
curl -k -X POST "$NODE/api/v1/access/users/alice@local/tokens" -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"ci","comment":"deploy pipeline","privsep":true,"expires_at":"2027-01-01T00:00:00Z"}'
{
"token": { "id": "alice@local!ci", "user": "alice@local", "name": "ci", "comment": "deploy pipeline", "privsep": true,
"expires_at": "2027-01-01T00:00:00Z", "legacy": false, "rev": 1, "created_at": "2026-10-03T10:00:00Z", "last_used_at": null },
"secret": "cst_…",
"note": "store this secret now; it is shown only once"
}
Then give the token its permissions with POST /api/v1/access/acl, subject
{"type":"token","id":"alice@local!ci"}. Revoke it with
DELETE /api/v1/access/users/alice@local/tokens/ci: it stops working at once,
and the sessions and consoles it opened close. last_used_at is the last use
the node you called saw. An operator key is listed with "legacy": true.
Sign-in methods
curl -k -X POST "$NODE/api/v1/access/realms" -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" -d '{
"id": "corp", "type": "oidc", "display_name": "Corporate sign-in",
"oidc": {
"issuer": "https://id.example.net/realms/corp", "client_id": "stratum", "client_secret": "…",
"groups_claim": "groups", "group_map": { "stratum-ops": "ops" },
"redirect_uris": ["https://node1.example.net:7070/console/auth/oidc/callback"]
}
}'
curl -k -X POST "$NODE/api/v1/access/realms/corp/test" -H "Authorization: Bearer $TOKEN"
client_secret is accepted and never returned: answers carry
has_client_secret. On a change, a setting you leave out stays as it is, the
client secret included. Defaults: scopes openid, profile and email;
username_claim preferred_username; autocreate true;
trust_provider_mfa false; allowed_algorithms RS256, ES256 and EdDSA. The
test answers what it found — ok, the provider's addresses, its signing keys
(id and algorithm) and any problems — without signing anyone in.
Refusals
| Status | Answer | When |
|---|---|---|
| 403 | you do not have permission to do this: it needs <privilege> on <path> | You may see it but not do this; missing_privilege and path name what is missing |
| 404 | The route's own not-found answer | You may not see it, or it does not exist |
| 403 | confirm your password to make this change | Confirm in the web console first (reauth_required: true) |
| 403 | an API token cannot make this change; sign in to the web console to make it | A token or operator key asked for such a change |
| 403 | set up a second factor to continue | A session that must set up its second factor first |
| 409 | you cannot grant a role with privileges you do not hold on <path> | Giving more than you have |
| 409 | built-in roles cannot be changed | A change to a built-in role |
| 409 | this account changed since you loaded it; reload and try again | if_rev no longer matches |
| 409 | this is the last account that can manage access; give another account Administrator first | The change would leave nobody who can manage access |
| 409 | access control is available once every node of this cluster runs version <v>; <n> nodes still need the update | A cluster with members on an earlier release |
| 503 | the cluster has no leader reachable from this node; changes to shared settings are paused until it has one | A change on a member that cannot reach the others |
Multi-tenancy
A tenant is one of your downstream customers on this node. Tenants have a
lifecycle (active → suspended → deleted), a resource quota, and their own
scoped API keys.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/tenant | List tenants |
| POST | /api/v1/tenant | Create a tenant (name required) |
| GET | /api/v1/tenant/{id} | Get a tenant |
| PUT | /api/v1/tenant/{id} | Update name and/or status |
| DELETE | /api/v1/tenant/{id} | Delete a tenant (cascades its keys, quota, networks & IPAM) |
| GET / PUT | /api/v1/tenant/{id}/quota | Read / set a tenant's quota |
| GET / POST | /api/v1/tenant/{id}/keys | List / mint scoped API keys |
| DELETE | /api/v1/tenant/{id}/keys/{kid} | Revoke a scoped key |
Create / list tenants
curl -k -X POST "$NODE/api/v1/tenant" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name":"acme-corp"}'
{
"status": "created",
"tenant": { "id": "t-9f3a21", "name": "acme-corp", "status": "active", "created_at": "2026-06-30T14:05:00Z", "updated_at": "2026-06-30T14:05:00Z" }
}
Returns 201. GET /api/v1/tenant returns { "tenants": [ ... ] }; status is
active, suspended, or deleted.
Update a tenant
PUT /api/v1/tenant/{id} — body: name and/or status (active, suspended,
deleted).
curl -k -X PUT "$NODE/api/v1/tenant/t-9f3a21" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name":"acme-corp","status":"suspended"}'
{ "status": "updated", "tenant": { "id": "t-9f3a21", "name": "acme-corp", "status": "suspended", "updated_at": "2026-06-30T14:06:00Z" } }
Delete a tenant. DELETE /api/v1/tenant/t-9f3a21 returns
{ "status": "deleted", "id": "t-9f3a21" }. Deleting a tenant cascades cleanup of
everything scoped to it: its scoped API keys (which stop authenticating
immediately), its quota, and its private networks and IPAM pools/allocations.
Tenant quota
A quota caps how much bandwidth a tenant may use and, with
Compute (early access), how many virtual machines and
volumes it may have: on this node, or across the cluster, once every member runs a version that supports it.
0 means unlimited.
| Field | Type | Meaning |
|---|---|---|
max_bandwidth_bps | int64 | Bandwidth cap in bits/sec (0 = unlimited) |
max_vms | int | Virtual machines (0 = unlimited): on this node, or across the cluster, once every member runs a version that supports it. Checked when a machine is created; lowering it never touches existing machines. used_vms in the answer is this node's count; the cluster's count is in GET /api/v1/cluster/tenants/{id}/usage |
max_volumes | int | Volumes (0 = unlimited): across the cluster, once every member runs a version that supports it, on this node below it. Checked when a volume is created, restored or grown |
max_volume_bytes | int64 | The total size of the tenant's volumes on this node, in bytes (0 = unlimited) |
max_ips | int | Addresses the tenant may hold on this node (0 = unlimited). Checked when an address is bound: a new address past the cap is refused with 409, and an address the tenant already holds is never refused. Lowering it never releases an address. used_ips in the answer is the current count |
max_rules | int | Refused with 400 unless it is 0: nothing enforces a rule limit, because a tenant owns no firewall rules. A value stored before this was refused is listed under not_enforced in the answer |
PUT changes only the fields you send; every other field keeps its current
value, so setting one field can never silently lift another. It answers 400
for a body with nothing to change or a negative value (0 is how you say
unlimited), and 404 for a tenant that does not exist. A max_rules other
than 0 is refused for the reason in the table. In a cluster where not every member
runs a version that shares the machine and volume limits yet, a PUT that sets
max_vms, max_volumes or max_volume_bytes returns "scope": "member" and a
"note", because those limits then hold on each member separately.
curl -k -X PUT "$NODE/api/v1/tenant/t-9f3a21/quota" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"max_bandwidth_bps":1000000000}'
{
"status": "quota-set",
"quota": { "tenant_id": "t-9f3a21", "max_bandwidth_bps": 1000000000, "max_ips": 0, "used_ips": 2, "max_vms": 0, "used_vms": 0 }
}
The cap is applied on the way out of the node and behaves as described in Tenants & Bandwidth — TCP settles at the rate, traffic over it is dropped rather than queued. The address limit is set per node, the machine and volume limits are shared across the cluster, once every member runs a version that supports it, and a tenant's networks are not capped.
Tenant-scoped API keys
Mint a key that authenticates as the tenant but is confined to that tenant's resources — ideal for handing to the tenant's own automation or your
per-customer billing logic. Create body: name (label) and ttl_hours
(0/omitted = no expiry).
curl -k -X POST "$NODE/api/v1/tenant/t-9f3a21/keys" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name":"acme-automation","ttl_hours":720}'
{
"status": "created",
"key": {
"id": "k-7b1c44", "tenant_id": "t-9f3a21", "name": "acme-automation",
"created_at": "2026-06-30T14:07:00Z", "expires_at": "2026-07-30T14:07:00Z",
"secret": "tnk_3f8a...e91c", "note": "store this secret now; it is shown only once"
}
}
The secret is returned once at creation and never again. Store it
immediately; list responses omit it.
List → GET /api/v1/tenant/t-9f3a21/keys returns { "keys": [ ... ] } (no
secrets). Revoke → DELETE /api/v1/tenant/t-9f3a21/keys/k-7b1c44 returns
{ "status": "revoked", "id": "k-7b1c44" }. The key must belong to the tenant in
the path; a key of another tenant answers 404, as an unknown key does.
If the node cannot save the change, neither call reports success. A mint answers 500 and returns no key. A revoke answers 500 and says so: the key stops working at once, but it could work again after the agent restarts, so send the same call again — it saves the revocation. Deleting a tenant behaves the same way: 500 when it could not be saved, with the tenant's keys refused from that moment.
What a tenant-scoped key can do. These keys are meant for your customers, so a key can see its own tenant and look after its own keys, but it cannot change what you sell it or whether it is running:
| A tenant key can (its own tenant only) | Reserved for the operator (403 to a tenant key) |
|---|---|
GET /api/v1/tenant/{id} — the tenant | PUT / DELETE /api/v1/tenant/{id} — rename, change status, delete |
GET /api/v1/tenant/{id}/quota — its caps and usage | PUT /api/v1/tenant/{id}/quota — change any cap |
GET /api/v1/billing/tenants/{id} — its billing state | POST /api/v1/billing/tenants/{id}/suspend, /resume, /limit, /unlimit |
GET / POST /api/v1/tenant/{id}/keys, DELETE /api/v1/tenant/{id}/keys/{kid} — list, mint and revoke its own tenant's keys | Creating, deleting, resizing or re-plugging machines, and creating or deleting networks and volumes |
| The tenant portal routes below — its own machines, networks and public addresses, and its own tasks, resources and nodes (read only) | Everything else on the node: listing or creating tenants, the operator's /vms, /networks, /tasks, /resources, /nodes, /metrics and /license routes, cancelling a task, and every route outside its tenant |
A key minted with a tenant key belongs to the same tenant and never outlives the key that minted it: its expiry is capped at the minting key's, so a key you
hand out for a day cannot mint one that lasts forever. A tenant key with no expiry
mints keys that follow the ttl_hours you send. Anything the table does not list
as allowed is refused to a tenant key, including endpoints added in later
versions until they are listed here.
Minting a key with an account or API token needs Tenant.Keys on the
tenant and also everything the key lets its holder do there (see the tenant, its
machines and networks, power its machines, open their consoles, use the guest
agent); revoking one needs Tenant.Keys.
In a cluster, once every member runs this release, a tenant's keys belong to the whole cluster: a key minted on any member works on every member, and a revoked one stops on all of them. Minting and revoking are then shared changes: a member that cannot reach the others refuses them with 503 and changes nothing, because the change has to reach the cluster as a whole — mint or revoke on a member that can reach the others, or restore the network between them. Until every member runs this release, a key works on the node that issued it.
The tenant portal
These routes give a customer's key (and the web console's customer portal, which calls them) its own machines, networks and public addresses. The operator's token and keys may call them too, for any tenant.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/tenant/{id}/vms | The tenant's machines |
| GET | /api/v1/tenant/{id}/vms/{vmid} | One machine, with what its guest agent reports |
| GET | /api/v1/tenant/{id}/vms/{vmid}/metrics | The machine's own figures, in the Prometheus text format of /metrics |
| POST | /api/v1/tenant/{id}/vms/{vmid}/start | Start it |
| POST | /api/v1/tenant/{id}/vms/{vmid}/stop | Ask it to shut down (optional {"timeout_seconds": N}) |
| POST | /api/v1/tenant/{id}/vms/{vmid}/force-stop | Cut its power |
| POST | /api/v1/tenant/{id}/vms/{vmid}/restart | Restart it (optional {"force": true}) |
| POST | /api/v1/tenant/{id}/vms/{vmid}/password | Set a guest user's password through the guest agent: {"user": "…", "password": "…"} |
| POST | /api/v1/tenant/{id}/vms/{vmid}/console | A single-use console ticket: {"type": "serial", "force": false} (type is vnc, the default, or serial) |
| GET | /api/v1/tenant/{id}/networks | The tenant's private networks |
| GET | /api/v1/tenant/{id}/networks/{nid} | One network, with the tenant's machines on it |
| GET | /api/v1/tenant/{id}/addresses | The public addresses the tenant's machines hold, and their gateway |
| GET | /api/v1/tenant/{id}/vms/{vmid}/rrd | The machine's graphs: the same query and answer as /api/v1/rrd/vms/{id} (see Graphs) |
| GET | /api/v1/tenant/{id}/audit | The audit records of what the tenant's own keys did: portal sign-ins, power actions, password resets, consoles, key changes (see Audit log) |
- Only its own. A machine or network of another tenant — or of the operator — answers 404 exactly as an id that does not exist does, so a key learns nothing about what else runs on the node.
- What it shows of a machine. Its name, state, size, hostname, interfaces (address, MAC, network, bandwidth), open consoles (which kind and since when, not who opened them) and guest agent. The node's own device names and the operator's notes are not included; a machine in trouble carries a plain
state_reason. - A suspended tenant keeps every read. Start, stop, force stop, restart, password and console answer 403:
this account is suspended: its virtual machines are stopped, …. A console ticket issued before the suspension is refused when it is used. - Gates. The licence freeze refuses the power actions and password resets (the console ticket and every read follow the read gates, as the operator's do). A plan without Compute refuses the power actions and password resets; a plan without private networks refuses the networks and addresses routes.
- The console ticket works like the operator's (see Consoles): the answer's
pathis the WebSocket to open,/api/v1/vms/{vmid}/console/vnc|serial?ticket=…. The tenant key itself is not accepted on the WebSocket; the ticket is. - Every change a tenant key makes (power actions, password resets, console tickets, key changes) and every portal sign-in is recorded in the node's audit log, naming the key's id; the password never appears in a record or a log.
GET /api/v1/tenant/{id}/auditshows the tenant those records — the time, which of its keys, the address, the action, the machine and the outcome — and nothing of the operator's. - In a cluster, once every member runs this release, the portal routes answer from any member. The lists — machines, networks, addresses, tasks, resources, nodes and audit records — gather the tenant's objects from every member; a member that does not answer is left out, and the answer then carries
"partial": true. A machine, a network or a task on another member is found and acted on there, consoles included, through the member the customer called; the customer never names a node. When the member that holds a machine does not answer, the customer gets 503this machine's server is not answering right now; your machine keeps running. Try again shortly.The tenant's quota is still each node's (/api/v1/tenant/{id}/quotaanswers for the node you call). Audit records across members page with the answer'snext, passed back asbefore. - A person or API token may call these routes too. It needs
Tenant.Auditon the tenant, and then what the operator's own routes need:VM.Auditon the tenant to list its machines;VM.Audit,VM.PowerMgmt,VM.ConsoleorVM.GuestAgenton a machine to look at it, power it, open its console or reset a password;Network.Auditon the tenant for its networks and addresses.
The tenant's own tasks, resources and nodes, read only:
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/tenant/{id}/tasks | The tasks on the tenant's machines and volumes, whoever started them, newest first (filters: state, type, object, since, limit) |
| GET | /api/v1/tenant/{id}/tasks/{tid} | One of them |
| GET | /api/v1/tenant/{id}/resources | The tenant's machines, networks and volumes in one list, with their state |
| GET | /api/v1/tenant/{id}/nodes | The nodes the tenant has something on |
- A tenant's view of a task says what it did (
type), on which of its objects, how far it got, when it started and ended, and whether the tenant or the provider started it (started_by:youorprovider). A failed task says so in fixed words; the node, the key that started it and the server's own wording are not shown. Cancelling a task is the operator's. - A task, machine or network of anyone else answers 404 exactly as a missing one does.
- The power actions and password resets above answer with their task's id (
"task"), and aLocationheader naming the tenant's own view of it.
Customer portal accounts
A customer's account is a login for one tenant's portal (see Customer portal accounts). The operator's routes below manage accounts. The customer's own routes serve the customer's session in the web console. Neither is paused by a frozen license.
| Method | Path | Who may call it | Answer |
|---|---|---|---|
| GET | /api/v1/access/tenants/{id}/portal-users | Tenant.Audit on the tenant | {"portal_users": […]} |
| POST | /api/v1/access/tenants/{id}/portal-users | Tenant.Keys, and every power a tenant key has there (Tenant.Audit, VM.Audit, VM.PowerMgmt, VM.Console, VM.GuestAgent, Network.Audit) | 201 {"portal_user": {…}}, with "temporary_password" when "generate": true was sent |
| GET | /api/v1/access/tenants/{id}/portal-users/{uid} | Tenant.Audit | {"portal_user": {…}} |
| PUT | /api/v1/access/tenants/{id}/portal-users/{uid} | Tenant.Keys; any change other than {"enabled": false} also needs every power a tenant key has there | 200 {"portal_user": {…}} |
| DELETE | /api/v1/access/tenants/{id}/portal-users/{uid} | Tenant.Keys | 200 {"deleted": true} |
| POST | /api/v1/access/tenants/{id}/portal-users/{uid}/password | Tenant.Keys, and every power a tenant key has there | 200: {"temporary_password": "…"} when generated, otherwise {}. The account's sessions end, and it must change the password at its next sign-in |
| POST | /api/v1/access/tenants/{id}/portal-users/{uid}/second-factor/reset | Tenant.Keys, and every power a tenant key has there | 200 {"id": "…", "tfa_removed": true, "sessions_ended": true}. tfa_removed is false when the account had no second factor; its sessions end either way. The account sets up a second factor again at its next sign-in |
The create body is {"login": "…", "display_name": "…", "password": "…"}, or the same with "generate": true in place of the password. display_name and expires_at are optional, and give either password or generate, not both. The login is an email address in lower case:
{"login": "[email protected]", "display_name": "Acme owner", "generate": true, "expires_at": "2027-01-31T00:00:00Z"}
- Every update names the revision it changes.
if_revis required on every update, and a change made on an older copy is refused with 409this account changed since you loaded it; reload and try again. An update body looks like{"enabled": false, "if_rev": 3}. expires_atis an RFC 3339 time in UTC, such as2027-01-31T00:00:00Z.nullremoves the expiry.- The account view has
id(pu-, sixteen lowercase hexadecimal digits, then@portal),tenant_id,login,display_name,enabled,expires_at,must_change_password,second_factor(enrolled,recovery_codes_left),last_sign_in_at,created_atandrev. It never carries a password, a second-factor secret, a recovery code, a client address or a session. - Refusals. 404
portal user not foundfor an account the tenant does not hold. 409the cap of customer accounts for this tenant has been reached; remove an account first, orthe cap of customer accounts on this server has been reached, for a create past a cap. 409a customer account with that email address already existsfor a login in use. 400 with the password policy's sentence (a password must be at least 12 characters long, orthat password is too common; choose another) for a password the policy refuses. - Below the cluster's release gate, every account route answers 409
the customer portal needs every server in this cluster to be updated first; try again later, or contact your provider.
The customer's own routes:
| Method | Path | Answer |
|---|---|---|
| GET | /api/v1/tenant/{id}/account | {"account": {"login", "display_name", "tenant": {"id", "name", "status"}, "second_factor": {"enrolled", "recovery_codes_left"}, "must_change_password"}} |
| POST | /api/v1/tenant/{id}/account/password | Body {"current_password": "…", "totp": "…", "new_password": "…"}, with totp when an authenticator app is set up. 200 {"ok": true}. The account's other sessions end |
| POST | /api/v1/tenant/{id}/account/second-factor | {"action": "start", "current_password": "…", "totp": "…"}, with the password and a current code (the app's, or one recovery code, which is spent) when an authenticator app is already set up, answers 200 {"secret": "…", "otpauth_uri": "…", "qr": {"size": 49, "rows": […]}}, where qr is the QR code of the address as an enrolment gives it (null when the address is too long for one). {"action": "confirm", "totp": "…"} answers 200 {"recovery_codes": […]}, shown once. The old authenticator app stops working when the new one is confirmed |
| POST | /api/v1/tenant/{id}/account/recovery-codes | Body {"current_password": "…", "totp": "…"}, with totp when an authenticator app is set up. 200 {"recovery_codes": […]}. The old codes end |
- Only a portal account reaches these routes. A tenant key, a person, and an account of another tenant get the router's own 404, and so does a key on its own tenant's account routes.
- A restricted session may only do what its restriction names. A password the provider set allows the password change, and an account with no authenticator app yet allows setting one up. Anything else is refused with 403
your password was set by your provider; choose a new password to continue, orset up your authenticator app to continue; your provider needs a second factor on this account. - Refusals. 400
the current password or code was not acceptedfor a wrong current password or code. A wrong one counts toward the account's wait, which a sign-in meets too: while it lasts the route answers 429 withRetry-After. 400that code was not accepted; enter a code from your authenticator app, or one recovery codefor a wrong code at confirmation. 400choose a password you have not used beforefor a new password the same as the current one, and the policy's sentences for a new password the policy refuses.
Tenant usage
| Method | Path | Who may call it | Answer |
|---|---|---|---|
| GET | /api/v1/tenant/{id}/usage | Tenant.Audit on the tenant; a tenant key or a customer's account for its own tenant | The usage answer below |
The window is timeframe: live, hour (the default), day, week, month or year. Or give res with from and to. res is live, 1m, 10m, 1h or 12h (or 60, 600, 3600 or 43200 seconds), or an archive name (day, week, month or year). from and to are RFC 3339 times or Unix seconds. cf is avg (the default) or max. Give timeframe, or res with from and to, not both.
{"kind": "tenant", "id": "tnt-example", "timeframe": "hour", "archive": "day", "cf": "avg", "step": 60, "start": 1790000000, "end": 1790003600, "series": {"net_rx": [null, 12500.5], "net_tx": [null, 800.25]}, "totals": {"download_bytes": 45000000, "upload_bytes": 2880000, "points": 60, "points_with_data": 58}}
The example is abridged: each series has one value per point of the window.
- Series.
net_rx(download) andnet_tx(upload) have one value per point, oldest first.nullis a gap. Nothing about a node, a machine, an interface, a MAC address or a flag is in the answer. timeframeisnullwhen the window was given withfromandto.- Totals.
download_bytesandupload_bytesare always bytes, whatevercfasks for: the bytes the machines' counters moved over the window, so a machine that ran for part of a minute counts the part it ran. Withcf=maxthe series shows each point's peak, and the totals are the same as thecf=avganswer's. A direction with no figure at all isnull.pointscounts the points of the window, andpoints_with_datathose with a figure in either direction. - Refusals. 400
the graph window is not valid: <reason>for a window the server cannot read. 503the usage figures are not available on this server yet; try again in a few minutes, or contact your provider if it keeps happeningwhile the history cannot be read here. 404 for a tenant this node does not hold. - In a cluster, the answer adds up the members' series point by point, and their totals. A member that cannot answer is left out, and the answer carries
"partial": true. - A read. A frozen license never refuses it.
Portal name
| Method | Path | Who may call it | Answer |
|---|---|---|---|
| GET | /api/v1/tenant/{id}/portal-host | Tenant.Audit | {"host": "portal.example.net", "node_port": 7070}, with "host": null when the tenant has no name |
| PUT | /api/v1/tenant/{id}/portal-host | Tenant.Modify; refused while the license is frozen | Body {"host": "portal.example.net"}. 200 with the same answer. 409 that address already belongs to another customer on this server, or that name is one of this server's own names, and a portal there would keep staff from reaching the server by it; choose a name only customers use, or 422 enter a host name made of letters, digits and hyphens, with dots between the parts; wildcard names and addresses are not accepted |
| DELETE | /api/v1/tenant/{id}/portal-host | Tenant.Modify; refused while the license is frozen | 200, with "host": null |
node_portis the API port a front forwards to, 7070 by default.- Per node. Each node keeps its own name, and the names are not shared across a cluster. The rules are in The portal name.
- Not for customers. A tenant key and a customer's account cannot read or change it.
Billing automation (operator hook)
These endpoints are your hook for gating downstream customers. Your billing system
calls them — with a minted operator API key (apikeys mint), or better an API
token that holds only the Billing role on /tenants (see
Billing Integration) — to suspend a non-paying
customer, resume them on payment, or apply/clear a bandwidth limit. Reading a
tenant's billing state needs Tenant.Audit; suspend, resume, limit and unlimit
need Tenant.Billing on the tenant. A tenant here is one of your customers. A tenant-scoped key may read
its own tenant's billing state (GET /billing/tenants/{id}) but gets 403 on
suspend, resume, limit and unlimit — a customer cannot lift its own suspension or
cap. These are mutating calls and are frozen (403) while the node's license
is inactive.
| Method | Path | Purpose |
|---|---|---|
| POST | /api/v1/billing/tenants/{id}/suspend | Mark the tenant suspended and stop its workloads' traffic, both ways (see Billing Integration) |
| POST | /api/v1/billing/tenants/{id}/resume | Mark the tenant active and lift the suspension |
| POST | /api/v1/billing/tenants/{id}/limit | Apply an aggregate rate cap |
| POST | /api/v1/billing/tenants/{id}/unlimit | Remove the rate cap |
| GET | /api/v1/billing/tenants/{id} | Read the customer's billing state |
curl -k -X POST "$NODE/api/v1/billing/tenants/t-9f3a21/suspend" -H "Authorization: Bearer $TOKEN"
{ "id": "t-9f3a21", "status": "suspended" }
Rate-limit — body: rate_mbps (int64, Mbps). Negative is treated as 0;
capped at 1000000 (1 Tbps). Stored as rate_mbps × 1,000,000 bits/sec.
curl -k -X POST "$NODE/api/v1/billing/tenants/t-9f3a21/limit" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"rate_mbps":100}'
{ "id": "t-9f3a21", "max_bandwidth_bps": 100000000 }
unlimit returns { "id": "t-9f3a21", "max_bandwidth_bps": 0 }; GET returns
{ "id": "t-9f3a21", "name": "acme-corp", "status": "active", "max_bandwidth_bps": 100000000 }.
Enforcement happens on the node you call: call every node that carries the tenant's traffic. See Billing Integration.
CLI equivalent: cenvero-str-ctl billing suspend|resume|limit|unlimit|status <tenant-id>.
Container networking
Attach a container's network namespace to one of your managed private networks. The container claims a managed endpoint (IP + MAC) and is wired with a veth pair into the network's bridge — the same attach path a VM uses, so containers share the network's IP/MAC pool and firewall.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/containers | List attached containers |
| POST | /api/v1/containers/attach | Attach a container netns |
| GET | /api/v1/containers/{id} | Get one container |
| POST | /api/v1/containers/{id}/detach | Detach (frees the endpoint) |
Attach body:
| Field | Type | Required | Notes |
|---|---|---|---|
runtime | string | yes | lxc, docker, or podman |
network_id | string | yes | A managed network you've already created |
netns_pid | int | yes | The container init PID whose network namespace is the target |
container_id | string | no | Your runtime's container id (for tracking) |
ip | string | no | Request a specific IP; omitted = next free in the network |
firewall | bool | no | Apply the managed per-container firewall rule |
id | string | no | Supply your own record id; omitted = generated |
curl -k -X POST "$NODE/api/v1/containers/attach" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"runtime":"docker","network_id":"net-7a","netns_pid":48213,"container_id":"9c2f...","firewall":true}'
{
"status": "attached",
"container": {
"id": "c-12ab", "runtime": "docker", "container_id": "9c2f...", "netns_pid": 48213,
"veth_host": "cnv-veth-12ab", "veth_container": "eth0", "bridge": "cnv-user-br0",
"mac": "02:42:0a:00:00:05", "ip": "10.0.0.5", "network_id": "net-7a", "endpoint_id": "ep-31"
}
}
Returns 201. List → GET /api/v1/containers returns { "containers": [ ... ] }.
Detach → POST /api/v1/containers/c-12ab/detach tears down the veth, releases the
endpoint, and returns { "status": "detached", "id": "c-12ab" }.
Tasks
Every operation on a virtual machine, an image or a volume is recorded as a task: creating, starting, stopping, restarting, resizing, updating and deleting machines, adding and removing their interfaces, setting a guest password, downloading and importing images, creating, growing, attaching, detaching and deleting volumes, their snapshots, backups and restores, and moving a machine to another member. A task records who started it, what it acts on, how far it got, a log, and how it ended. Tasks are kept for 30 days (at most 20,000 per node).
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/tasks | Tasks, newest first |
| GET | /api/v1/tasks/{id} | One task |
| GET | /api/v1/tasks/{id}/log | Its log (start: the first line, from 1; limit: at most 2,000, default 500) |
| POST | /api/v1/tasks/{id}/cancel | Stop it, where the operation can stop safely |
GET /api/v1/tasks filters:
| Parameter | Meaning |
|---|---|
state | Comma-separated states: queued, running, succeeded, failed, cancelled, interrupted |
type | A type (vm.start), or every type under a prefix ending in a dot (backup.) |
object | Tasks on this machine, image, volume, snapshot or backup — a machine's history includes the attaching and detaching of its volumes |
owner | Tasks started with this key id (api-token for the node's token, root for its command line) |
tenant_id | Tasks on this tenant's objects (empty: the operator's own) |
since, until | Start time, RFC 3339 (2026-09-29T12:00:00Z) or a duration back from now (24h) |
limit | 1–500, default 50 |
curl -k "$NODE/api/v1/tasks?state=running" -H "Authorization: Bearer $TOKEN"
{
"node": "3f2a0c1e-9b7d-4c1a-8e2f-0123456789ab",
"tasks": [
{
"id": "tsk-3f2a0c1e9b7d-0mumq7fmz-a05dee",
"node": "3f2a0c1e-9b7d-4c1a-8e2f-0123456789ab",
"type": "backup.create",
"object": {"kind": "volume", "id": "vol-1a2b3c4d", "path": "/volumes/vol-1a2b3c4d"},
"related": {"kind": "backup", "id": "bk-5e6f7a8b"},
"tenant_id": "acme",
"owner": {"kind": "operator-key", "id": "ak-7f3c", "via": "api"},
"state": "running",
"status": "backing up",
"progress": {"done": 734003200, "total": 2147483648, "unit": "bytes", "percent": 34.2},
"cancellable": true,
"log_lines": 2,
"started_at": "2026-09-29T12:00:01.204Z",
"ended_at": null,
"duration_seconds": 41.6
}
]
}
- Who started it (
owner):operator-token(the node's API token),operator-key(an operator API key, by id),user(a person signed in to the web console, by account id),token(an API token, by its id),tenant-key(a customer's key, with its tenant),root(the node's command line) orsystem(the node itself). A task is listed to whoever started it and to whoever may see the object it worked on.viasays whether the request came straight to the API, through the web console (console) or from the command line (cli). A key's secret is never recorded. - Progress is in bytes for image downloads and imports, backups, restores and copies of an image into a volume;
totalis 0 when the size is not known in advance. It is updated at most once a second. - The log keeps a task's first 200 and last 1,800 lines (at most 256 KiB);
omittedsays how many lines between them are no longer kept. To follow a running task, ask again fromnextuntilendedis true. A log never holds a password, a key or user-data. - Cancel works for image downloads and imports, backups and restores (202; the task then ends
cancelled), for a node's update until the new version is installed (cancelled; nothing was installed), and for the cluster's rolling update, which stops before its next server: the server being updated finishes first. Anything else answers 409:this task cannot be cancelled; it will finish or roll back on its own. A finished task answers 409 too. Cancelling follows the licence freeze like any other change, except that a frozen licence never stops cancelling a node's update or the rolling update, just as it never stops starting them. - After a restart. A task that was running when the agent stopped reads
interruptedfrom the moment the agent starts again. When the node then finishes or undoes the operation — an unfinished download is discarded, an unfinished create is rolled back, a delete is finished, a backup still running is followed again, a stop still under way is completed — the task ends with that outcome and its log says so (settled after the agent restarted: …);interrupted_atstays on it. - Task ids (
tsk-…) are unique and sort by start time; the first part names the node the task ran on. - A tenant key cannot use these routes (403); it reads its own tasks through the tenant portal.
- In a cluster,
GET /api/v1/cluster/taskslists every member's tasks together, and a task begun on another member through this one names this one in its owner'svia(see Working with other members).
Task progress is also announced on the event stream
as task.started, task.progress and task.finished.
The same from the node's command line: cenvero-str-ctl task list|show|log|cancel
(see CLI Reference).
Resources and nodes
GET /api/v1/resources returns everything on the node in one list — the node
itself, its machines, networks, volumes, images and tenants — with each one's
state: what the web console's tree of objects is drawn from.
curl -k "$NODE/api/v1/resources?type=vm" -H "Authorization: Bearer $TOKEN"
- Every entry has
type(node,vm,network,volume,image,tenant),id,node,name,tenantandstatus, plus what matters for its type: a machine's desired state, flags, size, addresses and image; a network's range and gateway; a volume's size, machine and snapshot and backup counts; an image's size. - Filters:
type(comma-separated) andtenant_id(tenant_id=for the operator's own). - The answer carries an
ETag; send it back inIf-None-Matchand an unchanged list answers 304.
GET /api/v1/nodes lists the nodes you can manage from here: this node, and on
a member of a cluster every member. Each entry has
its id and name, self (the node you called), status (online,
offline, pending while it has not finished joining, or unknown before
this node has heard from it), stale (its objects are what it last reported)
and last_seen, its role in the cluster (leader, follower, non-voter
or pending; standalone on a node that is not in a cluster) and whether it
is a voter, its version, whether it is manageable from here (with the
reason when it is not), its api_address and cluster_address, its licence
(plan, state, days left and the features it includes — never the key, serial or
customer), whether Compute and Storage are ready (modules), how far its clock
is from this node's (clock_offset_ms) and when its cluster identity expires
(cert_expires_at). In the entry of the node you called, reason is empty
unless it is a member that is not taking part in its cluster (see
A member that is not taking part).
The node's entry, in both lists, also carries figures: its newest reading,
taken every 10 seconds, under the names and units of its
graphs — cpu and iowait in percent, load1, load5,
load15, mem_used, mem_total, swap_used, swap_total, root_used,
root_total, data_used, data_total, pool_used, pool_total in bytes,
net_rx and net_tx in bytes per second — and at, when it was taken. A
figure not known yet is left out (the rates need two readings). A machine's
figures are its graphs'.
A tenant key cannot use either (403); it has
/api/v1/tenant/{id}/resources and /api/v1/tenant/{id}/nodes (see
the tenant portal).
An account or API token sees in /resources only the objects it may see, and
in /nodes the full entry of a node only where it holds Sys.Audit on that
node (/nodes/<node id>). Elsewhere it gets a shorter entry — id, node,
name, self, status, online, stale, last_seen, manageable, the
licence's state, whether it allows changes and its features, and modules —
without figures, versions, addresses or cluster details. An account or token
that holds no right on anything gets no node at all.
Working with other members
On a member of a cluster (agent 1.0.0-rc.81 or later), the API of any member reaches every member. The member you call needs clustering in its licence; the member that holds the object does the work and applies its own licence state and rules, as if you had called it directly. A tenant key can use none of this (403); it has the tenant portal routes, which answer from any member.
Who you are is checked where the work is done. Once every member runs this release, the member that holds the object checks your account, API token or operator key for itself, and applies its own copy of the cluster's permissions: an account that was disabled, or a token that was revoked, is refused there too. The node API token is the exception: it exists only on its own node, which vouches for it to the others.
Each member's own address allowlist applies. A member that limits who may
reach its API (api_allowed_ips) judges your address — the address of the
client that called the first member — even when you reach it through another
member. If it does not accept your address, it refuses with the same 403
{"error":"forbidden: source address not allowed"} it would give you directly,
and the member you called passes it back unchanged. This applies to its
consoles too. The command line on a member is not affected: cluster leave and
cluster remove run there reach the leader whatever the leader's list says.
Another member's objects. Put /nodes/<node id> in front of any path of
this reference — local names the node you call:
curl -k -X POST "$NODE/api/v1/nodes/7c9e6679-7425-40de-944b-e07fc1f90ae7/vms/vm-9f8e7d6c/start" \
-H "Authorization: Bearer $TOKEN"
The request and the answer are the ones that path has on the node itself, and a
Location header in the answer points back through /api/v1/nodes/<node id>/….
Cluster settings are not reached this way: /api/v1/nodes/<node id>/cluster/…
is 400 — call /api/v1/cluster/… on any member instead.
The whole cluster in one list:
GET /api/v1/cluster/resources— every member's objects, as/resourceslists one node's, each with itsnode. A tenant is listed once, with thenodesit has resources on. A member that is not answering contributes its objects from its last answer, marked"stale": truewithlast_seen. Filters:type,tenant_id,nodeandstale;ETagand 304 as for/resources.GET /api/v1/cluster/tasksandGET /api/v1/cluster/audit— every member's tasks or audit records, newest first, with the same filters as on one node,limitup to 500, andnextto pass back for the next page. The members that did not answer are listed inunreachable, each with itsnode,nameandlast_seen. Each member keeps its own audit log: check one withGET /api/v1/nodes/<node id>/audit/verify.GET /api/v1/cluster/events— every member's events as one stream. Each frame'sid:isc:…: reconnect to the same member with it inLast-Event-IDto pick up where you left off. Anode.resyncevent ({"node": "<node id>"}) means one member's events could not all be caught up: reload that member's objects.resyncand the rest work as on one node. Traffic samples (TRAFFIC) are not included.
On a node that is not in a cluster, use /resources, /tasks, /audit and
/events: the /cluster/… forms need clustering in the licence.
A member that does not accept your address (its api_allowed_ips) is listed in
unreachable in the task and audit lists. The cluster-wide lists leave its
objects out for you: they are not in /api/v1/cluster/resources, and its events
are not in /api/v1/cluster/events. Its node entry stays, marked
"manageable": false, with the reason
node <name> does not accept requests from this address.
A member on an older release has its objects left out of the cluster-wide lists
the same way, until it is updated. Its node entry stays, marked
"manageable": false, with the reason
node <name> runs an older version; update it to see its objects here.
When another member cannot do it, the member you call answers for it:
| Status | Answer |
|---|---|
| 404 | no node <id> in this cluster |
| 409 | node <name> has not finished joining the cluster |
| 409 | node <name> runs a version that cannot be managed from here; update it, or use its own console at https://…/console/ (with console_url) |
| 409 | node <name>'s clock differs from this node's by <n> s; requests to it are refused until the clocks agree |
| 503 | node <name> is not answering (last seen <time>); try again when it is back (with last_seen) |
| 504 | node <name> did not answer in time |
| 502 | node <name> refused the request from this node; this node's log has the reason |
| 409 | node <name> runs a version that cannot check this account; update it, or use its own console at https://…/console/ (with console_url): you signed in with an account or an API token, and that member runs an earlier release |
A member that has just stopped answering is not treated as down at once. A
request sent to it in that time waits until the member you call gives up on it,
about 15 to 20 seconds after it stopped answering, and then gets the 503
above; from then on, requests to it get the 503 at once. The cluster-wide lists
mark the member "stale": true sooner, as soon as one attempt to read its
objects fails.
Who did what is recorded on both members: the member you called records a
forward naming the other member in detail.target, and the member that did
the work records the action itself, with via_node naming the member you
called (see Audit log).
Tags, notes and the brand
Tags and notes
Any machine, network, volume, image or tenant, and the node itself, can carry tags and notes. Who may read or change them is decided by the object's own privileges, never by a tag.
| Method | Path | Read / change needs |
|---|---|---|
| GET / PUT | /api/v1/annotations/vm/{id} | VM.Audit / VM.Config.Options on the machine |
| GET / PUT | /api/v1/annotations/network/{id} | Network.Audit / Network.Modify on the network |
| GET / PUT | /api/v1/annotations/volume/{id} | Storage.Audit / Storage.Allocate on the volume |
| GET / PUT | /api/v1/annotations/image/{id} | Image.Audit / Image.Allocate on the image |
| GET / PUT | /api/v1/annotations/tenant/{id} | Tenant.Audit / Tenant.Modify on the tenant |
| GET / PUT | /api/v1/annotations/node | Sys.Audit / Sys.Modify on this node |
{
"kind": "vm", "id": "vm-1a2b3c4d", "tags": ["prod", "web"],
"notes": "Migrated from the old rack.\nOwner: ops",
"rev": 3, "updated_at": "2026-10-11T09:00:00Z", "updated_by": "alice@local"
}
A change sends tags, notes and the rev it was read at. An object carries up
to 16 tags, each starting with a lower-case letter or digit and holding at most 32
lower-case letters, digits, ., _ or -; notes are plain text of at most 8 KiB.
If someone changed the object's tags or notes since you read them, the change is
409 this object's tags or notes changed since you opened it: read it again and
reapply. An object you may not see answers exactly like one that does not exist.
On a cluster, a tenant's and a node's tags and notes are the cluster's, and can be
changed once every member runs this version (until then 409). Tenant keys are
refused on every one of these routes, and a tenant's own views never carry tags
or notes.
GET /api/v1/resources gives each object its tags and has_notes, and
?tag=<tag> keeps the objects that carry it — never one the caller could not see
without it.
The brand
The provider's brand on the sign-in page, the customer portal and, if you choose, the operator's console. On a cluster it is the cluster's brand.
| Method | Path | Needs |
|---|---|---|
| GET | /api/v1/options/brand | Cluster.Audit |
| PUT | /api/v1/options/brand | Cluster.Modify, and the password again |
| PUT / DELETE | /api/v1/options/brand/logo | Cluster.Modify, and the password again |
| PUT / DELETE | /api/v1/options/brand/favicon | Cluster.Modify, and the password again |
| GET | /api/v1/options/tags | Anyone signed in |
| PUT | /api/v1/options/tags | Cluster.Modify |
{
"product_name": "Acme Cloud", "accent": "#1d6ae1", "accent_adjusted": true,
"has_logo": true, "has_favicon": false,
"support_text": "Support: 24/7", "support_url": "https://support.example.net",
"signin_notice": "", "brand_operator_ui": false, "brand_tenant_portal": true, "rev": 2
}
product_name(at most 64 characters) replaces "Stratum" where the brand applies;support_textis at most 256 characters,support_urlanhttps://address, andsignin_noticeat most 1024 characters, all plain text.accentis one colour,#rrggbb. An accent too light to read on the console's background is darkened, keeping its hue, until it reaches a contrast of 4.5 to 1;accent_adjustedsays so.brand_tenant_portal(on by default) applies the brand to the customer portal,brand_operator_ui(off by default) to the operator's console; the sign-in page wears it when either is on. The sign-in notice and the support line show on the sign-in page in any case, to anyone who reaches it.- A logo or favicon is sent as
{"type": "image/png", "data": "<base64>"}: a PNG, WebP or SVG image of at most 128 KB (a logo) or 32 KB (a favicon). An image's bytes must be what its type says. An SVG must be a plain drawing: one with scripts, event handlers, links, or images or styles from elsewhere is refused. - A change sends the
revit was read at; an older one is 409these settings changed since you opened them.
PUT /api/v1/options/tags sets a colour per tag, {"colours": {"prod": "#c0392b"},
"rev": 4}, for at most 256 tags; each tag then shows in that colour wherever it
appears.
Before sign-in, the console serves the brand to everyone at /console/brand.css,
/console/brand.json, /console/brand/logo and /console/brand/favicon.
Operations
Alerting
Define conditions (a threshold on a metric), attach actions (notify on fire), and review/acknowledge fired alerts.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/alerts | List fired alerts (?state=firing/resolved/acknowledged) |
| GET | /api/v1/alerts/conditions | List conditions |
| POST | /api/v1/alerts/conditions | Create a condition |
| DELETE | /api/v1/alerts/conditions/{id} | Delete a condition |
| POST | /api/v1/alerts/conditions/{id}/actions | Attach an action |
| POST | /api/v1/alerts/{id}/ack | Acknowledge an alert |
| POST | /api/v1/alerts/{id}/resolve | Resolve an alert by hand |
| GET | /api/v1/alerts/history | Full alert history |
Create a condition — metric_type (bandwidth, pps, vm_down, threat)
and operator (gt, lt, eq) are required; threshold, target
(default global), duration_secs (how long the condition must hold before it
fires; not for threat) and cooldown_secs (default 300; the shortest time
between two alerts for the same condition and target) are optional. Both
durations are at most 2592000 (30 days). An id may be given: 1 to 64 letters,
digits, ., _ or -, starting with a letter or a digit. The body is read
strictly: any other key is 400, naming it, so a misspelt field cannot leave a
condition that does not do what it says. Returns 201 with the stored
condition, including the id it was given — use that id to attach actions or to
delete it. How conditions fire and resolve is described in
Monitoring.
curl -k -X POST "$NODE/api/v1/alerts/conditions" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"metric_type":"bandwidth","operator":"gt","threshold":900000000,"target":"global","duration_secs":60,"cooldown_secs":300}'
{ "condition": { "id": "3f1c9a0e5b7d4c2a8e6f1b0d9c3a7e5f", "metric_type": "bandwidth", "threshold": 900000000, "operator": "gt", "duration_secs": 60, "target": "global", "cooldown_secs": 300 } }
A connections or quota condition is refused with 400: nothing on a node
measures either. A condition that cannot work as stored (one of those, kept from
an earlier version) is listed with a warning explaining why.
Attach an action — type is websocket, webhook, or log; for webhook,
config is the URL to POST to when an alert fires or resolves, and secret
optionally sets the signing secret (one is generated when omitted). A log or
websocket action takes no config and no secret (400), and an unknown key
is 400. Each type can be attached once per condition; attaching it again
replaces it. Returns 201;
for a webhook the answer carries the secret — the only time it is shown.
curl -k -X POST "$NODE/api/v1/alerts/conditions/3f1c9a0e5b7d4c2a8e6f1b0d9c3a7e5f/actions" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"type":"webhook","config":"https://hooks.example.net/stratum"}'
{
"condition_id": "3f1c9a0e5b7d4c2a8e6f1b0d9c3a7e5f",
"type": "webhook",
"config": "https://hooks.example.net/stratum",
"secret": "whsec_EXAMPLE_shown_once_store_it_now"
}
The URL must reach a public address (the same rule as for event webhooks, below),
otherwise the call answers 400. Deliveries are signed and carry the same
headers as event webhooks, with X-Stratum-Event: ALERT, X-Stratum-Delivery
set to the alert id followed by -firing or -resolved, and User-Agent:
cenvero-stratum-alert/1; the body is the alert:
{
"id": "a55e0c1d2b3f4a5b6c7d8e9f0a1b2c3d",
"condition_id": "3f1c9a0e5b7d4c2a8e6f1b0d9c3a7e5f",
"metric_type": "bandwidth",
"target": "global",
"value": 912345678,
"state": "resolved",
"fired_at": "2026-09-28T14:02:05Z",
"resolved_at": "2026-09-28T14:09:40Z",
"resolved_reason": "cleared"
}
A failed delivery is tried up to three times; the delivery id stays the same, so a receiver can ignore a repeat.
Acknowledge an alert. The acknowledgement is recorded as the caller who makes
it, named as the audit log names it (a person alice@local, an API token
alice@local!ci, an operator key api key ak-1), and takes no body; a by field is
refused with 400:
curl -k -X POST "$NODE/api/v1/alerts/a-55/ack" -H "Authorization: Bearer $TOKEN"
{ "acknowledged": "a-55", "by": "alice@local" }
Resolve an alert by hand. It takes no body and answers the alert, resolved with
resolved_reason manual; its actions are told, as when it clears. If the
condition still holds, it fires again once its duration and cooldown allow. An
alert that is not there is 404, one already resolved 409. A frozen licence
stops neither the acknowledgement nor the resolution:
curl -k -X POST "$NODE/api/v1/alerts/a-55/resolve" -H "Authorization: Bearer $TOKEN"
GET /api/v1/alerts and /alerts/history return { "alerts": [ ... ] } /
{ "history": [ ... ] }, newest first. An alert's state is firing,
acknowledged (still open) or resolved; a resolved alert has resolved_at and
resolved_reason (cleared, not_reported, condition_removed, superseded
or manual). Resolved alerts are kept for 30 days, and at most the 10,000 most
recent alerts are kept. Deleting a condition resolves its open alerts and returns
{ "removed": "<id>" }.
POST /api/v1/alertsis not a fire endpoint — alerts fire from configured conditions. It returns400pointing you to the condition/ack subpaths above.
An email action — type email, config up to 10 addresses separated by
commas — is accepted only once a mail server is set in the notification settings.
Notification settings
The mail server email actions send through. On a cluster they are the cluster's
settings, and they can be changed once every member runs this version (until
then, 409 this setting becomes available when every server of the cluster
runs this version).
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/options/notifications | The settings (Cluster.Audit) |
| PUT | /api/v1/options/notifications | Change them (Cluster.Modify, and the password again) |
| POST | /api/v1/options/notifications/test | Send a test message (Cluster.Modify) |
{
"smtp": { "host": "mail.example.net", "port": 587, "tls": "starttls", "username": "alerts",
"has_password": true, "from": "[email protected]", "has_ca": false },
"rev": 1
}
The password and the authority's certificate are never answered: has_password
and has_ca say whether they are set. A change sends smtp — host, port,
tls (starttls or implicit: mail is never sent unencrypted), username,
password, from and ca_pem — and the rev it was read at. Leaving out
ca_pem keeps it; leaving out password keeps it only while the server stays the
same — a change of host (other than its letter case), port, tls or ca_pem
clears it unless the change sends one. "" clears either. An unknown field is 400,
naming it. A change made against an older rev is 409 these settings changed
since you opened them. A mail server at an address mail is never sent to (the
node itself, a link-local, multicast, reserved or broadcast address, a cloud metadata
service, or an address that leads to one of these) is 400. Changing the
settings needs the password again: see
Access control.
curl -k -X PUT "$NODE/api/v1/options/notifications" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"smtp":{"host":"mail.example.net","port":587,"tls":"starttls","username":"alerts","password":"…","from":"[email protected]"},"rev":1}'
POST /api/v1/options/notifications/test with {"to":"[email protected]"} sends one
message now and answers {"sent": true} once the mail server accepted it. A
server that offers no encryption is 502 the mail server did not offer an
encrypted connection; mail is never sent unencrypted; with no mail server set it
is 409; more than 5 tests a minute is 429. A failure is answered in fixed
words: what the mail server said is never repeated. Neither the test nor resolving
an alert is stopped by a frozen licence.
Self-healing
The node runs periodic health checks and repairs what it can.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/heal | Latest check results |
| POST | /api/v1/heal/check | Run the full sweep now (returns fresh results) |
curl -k "$NODE/api/v1/heal" -H "Authorization: Bearer $TOKEN"
{
"checks": [
{ "name": "bridge-mgmt", "healthy": true, "last_checked": "2026-06-30T14:11:00Z" },
{ "name": "bridge-user", "healthy": false, "error": "link down", "repaired": true, "last_checked": "2026-06-30T14:11:00Z" }
]
}
Each check reports name, healthy, and last_checked; plus error,
repaired, and repair_error when relevant.
Backups
Create config/full backups, list them, stage a full backup for a rollback, and
manage schedules. A config backup is a readable export of the node's firewall
rules (every setting of each), the firewall's default action, and its networks
and address pools, kept for your records; it cannot be restored. A full backup
holds the node's complete state, the firewall included, and is what you roll
back to. A backup whose settings cannot be read fails with an error rather than
leaving them out.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/backups | List backups |
| POST | /api/v1/backups | Create a backup (type: config (default) or full) — a task |
| POST | /api/v1/backups/restore | Stage a full backup for a rollback (ref: its id or file name) — a task |
| GET | /api/v1/backups/schedules | List schedules |
| POST | /api/v1/backups/schedules | Create a schedule |
| DELETE | /api/v1/backups/schedules/{id} | Remove a schedule |
curl -k -X POST "$NODE/api/v1/backups" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"type":"full"}'
{ "status": "started", "type": "full", "task": "t-3f1c9a0e" }
A backup and a restore answer 202 with a task (see Tasks): a full
backup can take longer than a request may. One backup or restore runs at a time
on a node; another is refused with 409 naming the running task. A backup is
listed only once it has been read back intact; one that does not read back is
discarded. The body is read strictly: a misspelt field is 400.
{ "backups": [ { "id": "bk-02", "type": "full", "file": "backup-full-20260630T141200Z.tar.gz", "size": 20480, "created_at": "2026-06-30T14:12:00Z", "present": true } ] }
The listing names each backup by its file, never where it is on the host, and
present is false when the file has since been removed or cut short.
Restore — only a full backup can be restored. The node unpacks and checks
it into a staging area; the running node is never replaced while the agent runs,
and the task's log ends with the step that completes the rollback: stop the
agent, put the staged snapshot in place, and start it again. A damaged archive,
one without a database, or one whose database fails its check is refused, and
nothing is staged. A config backup is refused with 400 (*only a full backup
can be restored; a config backup is an export of the node's settings for your
records and is not applied*); a reference outside the node's backups is 400,
and one that names no backup file is 404. These refusals come before a task
begins.
Create a schedule — expression (daily@HH:MM, weekly@DAY-HH:MM or
every-Nh; required), type (config (default) or full), retention (1 to
1000, default 7). The times are UTC, whatever the host's own time zone, and
each schedule says so ("timezone": "UTC"). Retention removes only that
schedule's own backups, never one made by hand or by another schedule. A
scheduled backup is a task too, so a failure shows in the task list.
curl -k -X POST "$NODE/api/v1/backups/schedules" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"expression":"daily@03:00","type":"config","retention":14}'
{ "schedule": { "id": "sch-01", "expression": "daily@03:00", "type": "config", "retention_count": 14, "next_run": "2026-07-01T03:00:00Z", "timezone": "UTC" } }
Delete → { "removed": "sch-01" }.
Certificates
This node's own certificate for its API (see TLS/SSL & License Operations).
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/tls | The certificate: mode, origin, expiry, names, and what is pending (Sys.Audit) |
| POST | /api/v1/tls/domains | Add a name ({"domain":"node1.example.net"}) and request a new certificate — a task |
| DELETE | /api/v1/tls/domains/{domain} | Remove a name and request a new certificate — a task |
| POST | /api/v1/tls/request | Request a certificate from the panel now — a task |
| POST | /api/v1/tls/pull | Collect an approved certificate now — a task |
{
"mode": "ca", "origin": "ca-signed", "expires_at": "2027-01-09T00:00:00Z", "days_remaining": 90,
"domains": ["node1.example.net"],
"pending": { "approval": false, "domain_change": false, "offline_csr": false }
}
expires_at and days_remaining are null while no certificate is held. Each
change answers 202 with its task; the task ends succeeded with the status
issued, pending (the request waits for approval in your account: the normal
path, never a failure), valid or unchanged, or failed in fixed words. One
certificate change runs at a time on a node, with the command line's: another is
409, naming the running task. A name that is not a plain hostname is 400.
None of these is stopped by a frozen licence. No route installs a certificate, a
key or a chain: an offline CSR, installing a signed certificate and the resets are
root's commands on the node.
Updates
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/update | What runs, what is installed, staged, offered and kept to roll back to (contacts nothing) |
| POST | /api/v1/update/check | Ask the update server what it offers (installs nothing) |
| POST | /api/v1/update/apply | Install the version on offer and restart into it — a task |
| POST | /api/v1/update/rollback | Return to the version this server last ran — a task |
| GET | /api/v1/cluster/update | The rolling update's plan (Plan feature: clustering) |
| POST | /api/v1/cluster/update | Start the rolling update — a task (Plan feature: clustering) |
{
"running_version": "1.0.0-rc.83", "installed_version": "1.0.0-rc.83", "channel": "prerelease",
"policy": "stage", "last_check_at": "2026-10-11T09:00:00Z",
"available": { "version": "1.0.0-rc.84", "build_time": "2026-10-10T12:00:00Z" },
"staged": { "version": "1.0.0-rc.84" },
"restart_pending": false, "floor": "1.0.0-rc.83",
"rollback": { "available": true, "version": "1.0.0-rc.82" },
"busy": null
}
restart_pending is true while a version is installed and not yet running;
staged is a version a cluster member has downloaded and checked and not
installed. POST /api/v1/update/apply takes an optional version — the one you
expect to be offered: another is 409 this server is offered version <v>, not
<w>; check for updates again. An apply or a rollback while one runs is 409
an update is already being applied on this server. None of these routes is
stopped by a frozen licence.
GET /api/v1/cluster/update lists every member in the order the rolling update
takes them, with what each runs and is offered, whether the update can start
(startable) and, if not, why (refusals); after an update that stopped, last
says where and why. POST /api/v1/cluster/update with an optional version starts
it and answers 202 with its task. It is refused before anything begins when
the caller may not update every member (403 you may not update every server
of the cluster), when the members are not all offered the same version (409
every server must be offered the same version), or when a member cannot be
reached (409 <name> cannot be reached; every server must be online to update
the cluster). How it proceeds is in Upgrades.
Configuration export
GET /api/v1/config/export downloads the node's settings as one JSON document
(config export on the command line prints the same): every firewall rule, the
firewall's default action, and the node's networks and address pools, as a config
backup holds them. A value whose name says it holds a secret is left out. A part
that cannot be read fails the whole export, rather than leaving it out.
curl -k "$NODE/api/v1/config/export" -H "Authorization: Bearer $TOKEN" -o config-export.json
{ "rules": [ … ], "firewall_default_action": "accept", "networks": [ … ], "pools": [ … ] }
System log
GET /api/v1/syslog reads the node's own log lines back from the host's system
log (the one journalctl reads), newest first, 100 at a time (?lines= up to 1,000). ?source=watchdog
reads the watchdog's lines instead of the agent's, and ?level= (debug, info,
warn or error) keeps that level and worse — so a page can hold fewer lines than
asked for. Each page gives newer_cursor, for the lines after it
(?after_cursor=), and older_until, for the lines before it (?until=); an older
page may repeat lines from the same second.
{
"entries": [
{ "time": "2026-10-11T09:00:00.123Z", "source": "agent", "level": "warn", "message": "bgp: neighbor down", "fields": { "neighbor": "192.0.2.1" } }
],
"newer_cursor": "s=0a1b2c3d;i=4f2;b=5e6f;m=1a2b;t=60f1;x=7c8d",
"older_until": 1760173200
}
What the log never shows: lines the audit log keeps (read those through the Audit log); the value of anything whose name says it is a secret (a token, a password, a key, a ticket, a cookie, an authorization, a licence, a credential); the value of anything named for who a line is about (an account, a user, an actor, a subject, an email address) or for a client, such as the address a sign-in came from, which the audit log has; anything in PEM form, such as a key; the query, fragment and user part of any address; the directories of a path on the host (a path keeps its last element); and more than 4 KiB of any one line. One read runs at a time, for at most 10 seconds: a read while another runs, or one that takes longer, is 503 with a sentence of its own, and so is a host whose system log cannot be read. An unknown parameter is 400.
Node dashboard
GET /api/v1/dashboard — one aggregated snapshot of the node for a status
screen, in a single request instead of polling a dozen endpoints. Every figure is
read from the node itself. A figure the node cannot read — or a subsystem that is
not running — is null, never a made-up 0, so an idle node and an unknown
one look different.
curl -k "$NODE/api/v1/dashboard" -H "Authorization: Bearer $TOKEN"
{
"host": { "hostname": "node-a", "uptime_secs": 86400, "cpu_cores": 16, "memory_mb": 64214 },
"nics": [ { "name": "cnv-nic-0", "speed_mbps": 10000, "rx_bytes": 481920512, "tx_bytes": 90211844, "status": "up" } ],
"traffic": { "total_bytes_in": 9120384, "total_bytes_out": 7730112, "active_flows": 73 },
"security": { "blocked_packets": 1204, "active_rules": 12, "threat_detections": 0 },
"active_alerts": [],
"cluster": { "enabled": false, "node_count": 1, "leader_id": "", "state": "disabled" }
}
| Field | Meaning |
|---|---|
host | Hostname, uptime in seconds, CPU cores, total memory in MB |
nics | Each network card, with its byte counters |
traffic.total_bytes_in / total_bytes_out | Bytes through packet processing since it was last loaded |
traffic.active_flows | Connections being tracked now |
security.blocked_packets | Packets dropped by policy — firewall, blocked addresses, anti-spoofing, MAC binding and rate limits — since packet processing was last loaded |
security.active_rules | Firewall rules in force right now: every rule except scheduled ones whose window is closed |
security.threat_detections | Intrusion-detection hits so far |
active_alerts | Alerts currently firing |
cluster | Whether clustering is on, how many members (1 when it is off), the leader's id, and this node's role |
The dashboard is the figures of this moment, with no per-machine figures and no peak rate. For history — the node's CPU, memory, disks and traffic, each interface's and each machine's — see Graphs.
Graphs
The node keeps the history of its own figures, of each interface it manages and of each virtual machine, for graphs — no collector needed. Reads, never refused by a licence freeze or a plan.
| Method | Path | Series |
|---|---|---|
| GET | /api/v1/rrd/node | cpu, iowait (percent of all cores); load1, load5, load15; mem_used, mem_total, swap_used, swap_total; root_used, root_total, data_used, data_total, pool_used, pool_total (bytes); net_rx, net_tx (bytes per second on the node's network cards). The answer also lists the interfaces that have a history |
| GET | /api/v1/rrd/interfaces/{name} | rx, tx, bytes per second |
| GET | /api/v1/rrd/vms/{id} | cpu (percent of the machine's own vCPUs); mem_used (host memory it occupies), mem_total (memory the guest has); disk_read, disk_write, net_rx, net_tx (bytes per second, network from the machine's side) |
Query parameters:
| Parameter | Values |
|---|---|
timeframe | live (every 10 s for a node, about the last hour; every 15 s for a machine or tenant, about the last 90 minutes), hour, day (a point a minute), week (every 10 minutes), month (every hour), year (every 12 hours). Default hour |
res, from, to | Instead of timeframe: a resolution (live, 60, 600, 3600, 43200 seconds, or 1m, 10m, 1h, 12h) and a range (RFC 3339 or Unix seconds). With from alone, the finest resolution that reaches back that far |
cf | avg (default): the average of each point; max: its maximum |
curl -k "$NODE/api/v1/rrd/node?timeframe=day" -H "Authorization: Bearer $TOKEN"
{
"kind": "node", "id": "node", "timeframe": "day", "archive": "day", "cf": "avg",
"step": 60, "start": 1790035200, "end": 1790121540,
"series": { "cpu": [3.2, 2.9, null, 4.1], "mem_used": [2147483648, 2151677952, null, 2155872256] },
"interfaces": ["cnv-mgmt-br0", "cnv-nic-0", "cnv-user-br0"]
}
Point i covers the step seconds from start + i × step (Unix seconds, UTC);
the last point is the one in progress. null is a gap: nothing was measured
then (the node was off, the machine was stopped). A machine that exists but has
not run answers an empty history; one that does not exist, 404. The history
takes a fixed amount of disk; see Monitoring.
Tenant keys are refused here (403); a tenant reads its own machines'
graphs at GET /api/v1/tenant/{id}/vms/{vmid}/rrd, where another tenant's
machine or the operator's answers 404 like one that does not exist.
Audit log
Every change made on the node — through this API, the web console, the tenant
portal or cenvero-str-ctl — is recorded, with console sign-ins and machine
consoles. Reads are not recorded. No record holds a key, token, password or
request body. See Monitoring for what is recorded and how
long it is kept.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/audit | Records, newest first, with filters and pages |
| GET | /api/v1/audit/export | Every matching record as JSON lines (application/x-ndjson), oldest first, streamed |
| GET | /api/v1/audit/verify | Check the whole log; ?checkpoint=<seq>:<hash> also checks a record you kept |
| GET | /api/v1/tenant/{id}/audit | A tenant's own records (see The tenant portal) |
Filters (all optional, for the list and the export):
| Parameter | Keeps |
|---|---|
since, until | Records from / up to a time: RFC 3339 or Unix seconds |
principal | One principal, exactly as listed: api token, api key ak-12ab, alice@local (a person), alice@local!ci (an API token), tenant key tk-… (tenant t-acme), root |
kind | operator-token, operator-key, user, token, tenant-key, root (the node's command line), system (the node itself), unauthenticated |
tenant | Records made with one tenant's keys |
action | Actions starting with this: vms. matches vms.start, vms.delete, … |
object | Objects starting with this: /vms/vm-1a2b3c4d |
outcome | success, failure or refused |
limit | 1–1000 records (default 100) |
before, after, order | Pages: pass the answer's next as before for the next page; after=N or order=asc reads oldest first |
curl -k "$NODE/api/v1/audit?action=vms.&outcome=refused&limit=20" -H "Authorization: Bearer $TOKEN"
{
"records": [
{
"seq": 1204, "time": "2026-09-29T14:03:11.52Z", "node": "7c1e…",
"principal": "tenant key tk-5f2a (tenant t-acme)", "principal_kind": "tenant-key",
"tenant": "t-acme", "via_node": "", "session_ref": "3fa9c0d2e1b4",
"client_ip": "203.0.113.9", "request_id": "9b1f…",
"method": "POST", "route": "/api/v1/tenant/{id}/vms/{vmid}/start", "object": "/vms/vm-1a2b3c4d",
"action": "tenant.vms.start", "outcome": "refused", "status": 403, "task_id": "",
"detail": { "refused_by": "licence" },
"prev_hash": "5e0c…", "hash": "a91b…"
}
],
"next": 1204
}
| Field | Meaning |
|---|---|
seq | The record's number: 1, 2, 3, … on each node, with no holes |
principal, principal_kind | Who: a credential's name, never the credential |
tenant | Set when a tenant's own key acted |
via_node | In a cluster, the member the request was made on, when another member passed it to this one (empty otherwise). The member it was made on records a forward, with detail.target naming this node |
session_ref | The web-console session the change came through |
client_ip, request_id | Where it came from; your X-Request-ID is kept when it is a plain id |
method, route | The API route (method is IPC and route the command for the command line) |
object, action | What it acted on, and a short name for what it did |
outcome, status | success, failure or refused, and the status code answered |
task_id | The task the change began, or the task a task record is about |
detail | created (the id of what a create made), refused_by (authentication, permission, tenant scope, licence or plan), for consoles console, reason, duration_seconds, and identity_stale ("true" on a record a cluster member wrote while its access settings may have been out of date — see In a cluster) |
prev_hash, hash | The chain: the fingerprint of the record before, and of this one |
Tasks. Besides the record of the request that began a task, the task's start
and end are records of their own: method is TASK, route the task type
(vm.create, image.download, …), action one of task.started,
task.succeeded, task.failed, task.cancelled or task.interrupted (the node
restarted while it ran; when the node then finishes or undoes the work, its end
follows), and principal whoever started it. They never hold the task's log or
error; read those at /api/v1/tasks/{id}. A tenant sees the task records of the
tasks its own keys began.
Verify walks every record and answers:
{ "ok": true, "checked": 48211, "first_seq": 1, "last_seq": 48211, "head_hash": "a91b…" }
When the chain is broken, ok is false and broken names the first record
where it breaks and why — a record changed after it was written, a record
missing, one that does not link to the record before it, or records removed
without the removal record retention leaves. Keep last_seq and head_hash
somewhere off the node: ?checkpoint=<last_seq>:<head_hash> later tells you
whether the log was rewritten since (checkpoint.matches).
Checking an export yourself. Each exported line is one record. Its hash is
the SHA-256 of: the text cenvero-stratum-audit-v1 and a newline; then
prev_hash; seq and the time (Unix nanoseconds) as 8-byte big-endian
integers; node, principal, principal_kind, tenant, via_node,
session_ref, client_ip, request_id, method, route, object, action,
outcome; status as an 8-byte big-endian integer; task_id; and detail as
compact JSON with its keys sorted (empty when there is none) — each text field
as a 4-byte big-endian length followed by its bytes. Each record's prev_hash
is the previous record's hash (64 zeros for record 1).
A cluster. Each member keeps its own log, with its own chain.
GET /api/v1/cluster/audit lists every member's records together, and each
member's chain is checked on that member (see
Working with other members).
Tenant keys are refused on /api/v1/audit and its sub-routes (403). At
GET /api/v1/tenant/{id}/audit a tenant key reads the records its own tenant's
keys made — seq, time, principal, client_ip, request_id, action,
object, outcome, status — with the same filters; another tenant's id is
refused.
Not implemented
These paths exist on the router and return 501 Not Implemented with an explanation. They are listed here so you do not spend time discovering by experiment that they return nothing useful.
| Method | Path | Use instead |
|---|---|---|
| GET | /api/v1/topology | Build it from /networks, /bridges, /nics, /cluster/status |
| POST | /api/v1/cluster/profile | Nothing to select — every node runs the same services |
| PUT | /api/v1/lb/{id} | Delete the VIP and create it again |
Each answers 501 with a message naming the alternative. They previously returned
a success-shaped body — an empty topology, for example — which
is indistinguishable from a real, empty answer. POST /api/v1/config/batch is
gone and answers 404; read the node's settings with
GET /api/v1/config/export. A 501 you
can branch on is more useful than a success you cannot trust.
Event log (Server-Sent Events)
Stream system events as they happen over a long-lived HTTP connection. For a push-style socket see the Real-time WebSocket section below.
GET /api/v1/events?categories=<CSV> — categories is an optional
comma-separated filter (uppercase). Omit it for all categories. Valid
categories:
TRAFFIC SECURITY BANDWIDTH DHCP DNS NETWORK ALERT SYSTEM LB CLUSTER COMPUTE
curl -k -N "$NODE/api/v1/events?categories=SECURITY,ALERT" -H "Authorization: Bearer $TOKEN"
The response is text/event-stream. Each event arrives as an SSE frame with an
id; heartbeats (: keepalive) hold the connection open:
: connected
retry: 3000
id: 3f2a0c1e-9b7d-4c1a-8e2f-0123456789ab:1790000000000042
event: COMPUTE
data: {"id":"b1c2...","seq":1790000000000042,"type":"compute.vm_state","category":"COMPUTE","timestamp":"2026-09-29T14:13:00Z","node":"3f2a0c1e-9b7d-4c1a-8e2f-0123456789ab","object":"/vms/vm-1a2b3c4d","tenant":"acme","severity":"info","payload":{"vm":"vm-1a2b3c4d","name":"web-01","tenant":"acme","state":"running","desired":"running","reason":"","flags":[]}}
: keepalive
Every event carries:
| Field | Meaning |
|---|---|
id | A unique id (random) |
seq | This node's sequence number: it only ever grows, also across agent restarts |
timestamp | When it happened, UTC |
node | The node it happened on |
object | What it is about, when it is about one thing: /vms/<id>, /volumes/<id>, /images/<node>/<id> |
tenant | The tenant that thing belongs to (absent for the operator's own) |
severity | info, warning or error |
Picking up where you left off. Each frame's id: line is <node>:<seq>.
Reconnect with it in the Last-Event-ID header (browsers do this on their own;
?last_event_id= works too) and the stream first sends every event you missed,
then carries on — nothing lost, nothing twice. The node keeps the last 2,048
events for this, and no more than 4 MiB of them; an event larger than 32 KiB is
sent to you as it happens but is not kept. When what you missed is no longer
there — too long ago, too large to keep, from before the agent restarted, or
from another node — or when you read too slowly and events were dropped, the
stream sends a resync event instead: reload what you show from the API. Traffic samples (TRAFFIC) are not kept for replay and
carry no id: line.
When the stream ends on its own. A stream opened with a key ends, with an
end event saying why, once that key is revoked or the node's token changes;
one opened through a web console session ends when the session does.
Every member of a cluster at once. GET /api/v1/cluster/events carries the
events of every member as one stream, with the same filter; see
Working with other members.
Events you will see for machines, volumes, tasks and the cluster:
| Type | Sent when |
|---|---|
compute.vm_state | A machine's state, desired state or flags change (state, desired, reason, flags) |
storage.volume_state | A volume's state, machine or size change; deleted when it is gone |
storage.schedule_ran, storage.schedule_failed | A volume backup schedule's run completes, or fails or ends busy. They name ids only |
compute.template_shared | A template's sharing changes (image, name, shared) |
task.started, task.finished | A task begins or ends (the whole task) |
task.progress | A running task's progress or status changes (at most once a second per task) |
cluster.membership | A node of the cluster was admitted, joined, given or relieved of a vote, or removed (node, name, change, voter; see Membership events) |
Real-time WebSocket
For a bidirectional, push-style stream, connect to the node's WebSocket endpoint:
wss://<node-ip>:7072/ws
Enable it once with cenvero-str-ctl service websocket on. The WebSocket
authenticates with the node API token only (not operator-minted or
tenant-scoped keys).
1. Connect & authenticate
Provide the token either as a query parameter or an Authorization header:
wss://<node-ip>:7072/ws?token=<api-token>
or Authorization: Bearer <api-token>.
Browser clients can't set request headers on a WebSocket, so use the?token=form there. TheOriginis restricted to the node's own host by default; configure additional allowed origins on the node (api_allowed_origins) if you connect from a different web origin.
2. Subscribe
After the socket opens, send a subscribe message naming the categories you want (uppercase, the same set as the SSE stream). Until you subscribe, no events are delivered. Subscriptions are additive; there is no acknowledgement message — matching events simply begin to flow.
{ "action": "subscribe", "categories": ["SECURITY", "ALERT", "NETWORK"] }
3. Receive events
Each event is delivered as a JSON text frame:
{
"id": "b1c2d3...",
"type": "alert.fired",
"category": "ALERT",
"timestamp": "2026-06-30T14:13:00Z",
"payload": { "condition_id": "cond-1", "value": 950000000 }
}
| Field | Type | Notes |
|---|---|---|
id | string | Unique event id |
type | string | Event type, e.g. alert.fired, firewall.block |
category | string | One of the categories above |
timestamp | string | UTC RFC 3339 |
payload | object | Event-specific detail (omitted when empty) |
Example — wscat
wscat --no-check -c "wss://node.example.net:7072/ws?token=$TOKEN"
# once connected:
> {"action":"subscribe","categories":["SECURITY","ALERT"]}
< {"id":"b1c2...","type":"alert.fired","category":"ALERT","timestamp":"2026-06-30T14:13:00Z","payload":{...}}
(--no-check skips TLS verification for a privately-managed node certificate
during testing; in production, trust the node's certificate instead.)
Example — browser
const ws = new WebSocket("wss://node.example.net:7072/ws?token=YOUR_API_TOKEN");
ws.onopen = () => {
ws.send(JSON.stringify({ action: "subscribe", categories: ["ALERT", "SECURITY"] }));
};
ws.onmessage = (e) => {
const evt = JSON.parse(e.data);
console.log(evt.category, evt.type, evt.payload);
};
A client that can't keep up with the event rate is dropped to protect the node; reconnect and re-subscribe to resume.
Event webhooks
Register HTTP endpoints that the node POSTs a signed event to when something
happens — an out-of-band, push-style alternative to holding open the SSE
/api/v1/events stream or a WebSocket. A webhook is a URL, an optional
event-category filter, and a per-webhook secret. Subscriptions are stored on the
node and survive a restart, and every delivery carries an HMAC-SHA256
signature so your receiver can verify it. Managing webhooks uses the standard
api_token bearer, like the rest of this API.
Delivery is fail-safe: events are handed to a bounded, out-of-band worker pool, so a slow, hanging, or broken receiver can never block the node's event processing or the other webhooks. Each delivery is attempted with a per-attempt timeout and a few retries with exponential backoff; if the delivery queue is ever full, the event is dropped (and counted) rather than blocking.
The URL must be http or https and reach a public address: the node
refuses loopback, private, shared (carrier-grade NAT), documentation and benchmarking
ranges, link-local addresses including the cloud metadata address, multicast,
unspecified, reserved and broadcast addresses, and an address that leads to one of
these, both when the webhook is registered and again on every delivery. A
receiver that answers with a redirect is not followed, and deliveries connect
directly — a proxy set in the agent's environment is not used.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/webhooks | List subscriptions (never includes secrets) |
| POST | /api/v1/webhooks | Register a subscription (returns the secret once) |
| GET | /api/v1/webhooks/{id} | Get one subscription |
| DELETE | /api/v1/webhooks/{id} | Delete a subscription |
| POST | /api/v1/webhooks/{id}/test | Send a one-shot test delivery |
Subscription fields
| Field | Type | Notes |
|---|---|---|
id | string | Server-assigned subscription id |
url | string | The http/https endpoint events are POSTed to |
categories | array | Event-category filter (uppercase); empty means every category |
created_at | string | UTC timestamp |
delivered | integer | Successful deliveries so far |
failed | integer | Deliveries that failed after all retries |
dropped | integer | Events dropped because the delivery queue was full |
last_status | integer | HTTP status of the most recent attempt (omitted until the first attempt) |
last_error | string | Most recent error, if any (omitted when the last attempt succeeded) |
The category filter uses the same uppercase categories as the event stream; an unknown category is rejected. Omit the filter (or send an empty list) to receive every category:
TRAFFIC SECURITY BANDWIDTH DHCP DNS NETWORK ALERT SYSTEM LB CLUSTER
Register a webhook
POST /api/v1/webhooks — body: url (required, http or https);
categories (optional filter); secret (optional). Omit secret and the node
generates a strong one (prefixed whsec_). Returns 201.
curl -k -X POST "$NODE/api/v1/webhooks" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"url":"https://hooks.example.com/stratum","categories":["SECURITY","ALERT"]}'
{
"webhook": {
"id": "9f1c2d3e4a5b6c7d",
"url": "https://hooks.example.com/stratum",
"categories": ["ALERT", "SECURITY"],
"created_at": "2026-06-30T14:20:00Z",
"delivered": 0,
"failed": 0,
"dropped": 0,
"secret": "whsec_EXAMPLE_shown_once_store_it_now"
}
}
Thesecretis returned only here, at registration — it is the HMAC key your receiver needs to verify deliveries. Store it now; list andGETresponses never include it. Lost it? Delete the webhook and register a new one.
List → GET /api/v1/webhooks returns { "webhooks": [ ... ] } (secret-free). Get
one → GET /api/v1/webhooks/9f1c2d3e4a5b6c7d returns { "webhook": { ... } }.
Delete → DELETE /api/v1/webhooks/9f1c2d3e4a5b6c7d returns
{ "deleted": "9f1c2d3e4a5b6c7d" }.
Delivery format
Each delivery is an HTTP POST with Content-Type: application/json. The body is
the event itself — the same JSON shape delivered over the SSE and WebSocket
streams (id, type, category, timestamp, payload). These headers
accompany every delivery:
| Header | Value |
|---|---|
X-Stratum-Signature | sha256= followed by the hex HMAC-SHA256 of the raw request body, keyed by your webhook secret |
X-Stratum-Event | The event category (e.g. SECURITY) |
X-Stratum-Delivery | The event id (matches id in the body) |
X-Stratum-Timestamp | Send time, Unix seconds (UTC) |
User-Agent | cenvero-stratum-webhook/1 |
Example delivered body:
{
"id": "b1c2d3e4f5",
"type": "firewall.block",
"category": "SECURITY",
"timestamp": "2026-06-30T14:20:05Z",
"payload": { "src": "203.0.113.7", "rule": "deny-inbound" }
}
Verify a delivery by recomputing the signature over the exact bytes you
received and comparing it (in constant time) to the X-Stratum-Signature header:
# body = the raw request body; SECRET = your webhook secret
printf '%s' "$body" | openssl dgst -sha256 -hmac "$SECRET"
# prepend "sha256=" to the hex digest, then compare to X-Stratum-Signature
Test a webhook
POST /api/v1/webhooks/{id}/test sends one synchronous test delivery — a
webhook_test event in the SYSTEM category — so you can confirm the receiver is
reachable and verifies the signature.
curl -k -X POST "$NODE/api/v1/webhooks/9f1c2d3e4a5b6c7d/test" \
-H "Authorization: Bearer $TOKEN"
{ "tested": "9f1c2d3e4a5b6c7d", "status": "delivered" }
If the receiver is unreachable or returns a non-2xx status, the call reports
502 with { "error": "...", "webhook_id": "..." } — the node is fine, the
downstream endpoint is not. An unknown id returns 404.
Bulk create
Two convenience endpoints create many items in one request, each item using the same shape as the corresponding single-create call. Every item is applied independently and the response reports per-item success or failure, so one bad item never aborts the rest.
| Method | Path | Per-item shape |
|---|---|---|
| POST | /api/v1/rules/batch | A firewall rule (as in POST /api/v1/rules) |
| POST | /api/v1/dns/records/batch | A DNS record (as in POST /api/v1/dns/records) |
Send the items as a JSON array under rules (firewall) or records (DNS). A
batch may hold up to 1000 items; an empty array, or one over the cap, is
rejected with 400. Firewall /rules/batch is available on any active plan;
/dns/records/batch requires the DNS plan feature. Both are mutating calls, so
they are frozen (403) while the node's license is inactive.
The response carries created and failed counts and a results array — one
entry per submitted item, in order, each with its index, an ok flag, and
either the created object (rule / record) or an error string. The HTTP
status reflects the batch as a whole:
| Outcome | Status |
|---|---|
| Every item created | 201 Created |
| Some created, some failed | 207 Multi-Status |
| No item created | 400 Bad Request |
Create several firewall rules:
curl -k -X POST "$NODE/api/v1/rules/batch" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"rules": [
{ "action": "drop", "protocol": "tcp", "dest_port": 23 },
{ "action": "drop", "protocol": "tcp", "dest_port": 2323 }
]
}'
{
"created": 2,
"failed": 0,
"results": [
{ "index": 0, "ok": true, "rule": { "id": 11, "chain": "prerouting", "priority": 0, "protocol": "tcp", "dest_port": 23, "action": "drop", "stateful": true } },
{ "index": 1, "ok": true, "rule": { "id": 12, "chain": "prerouting", "priority": 0, "protocol": "tcp", "dest_port": 2323, "action": "drop", "stateful": true } }
]
}
A partial batch (one item is missing a required field) returns 207, with the valid items created and the bad one reported in place:
curl -k -X POST "$NODE/api/v1/dns/records/batch" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"records": [
{ "zone_id": 1, "name": "a", "type": "A", "value": "10.20.0.1" },
{ "zone_id": 1, "name": "b", "type": "A" }
]
}'
{
"created": 1,
"failed": 1,
"results": [
{ "index": 0, "ok": true, "record": { "id": 20, "zone_id": 1, "name": "a", "type": "A", "value": "10.20.0.1", "ttl": 300 } },
{ "index": 1, "error": "zone_id, name, type and value are required" }
]
}
Host addressing
The step between a network reserved its gateway address and *something on the host answers on it*. Creating a network does not configure that address on an interface; this is how you do it.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/nics/{iface}/addresses | Addresses currently on an interface |
| POST | /api/v1/nics/{iface}/addresses | Put an address on it |
| DELETE | /api/v1/nics/{iface}/addresses/{cidr} | Remove one |
curl -k -X POST "$NODE/api/v1/nics/cnv-user-br0/addresses" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"address":"10.20.0.1/24"}'
{ "status": "configured", "interface": "cnv-user-br0", "address": "10.20.0.1/24",
"addresses": ["10.20.0.1/24", "fe80::.../64"] }
You usually do not need to name the interface. POST /api/v1/addresses defaults
to the workload bridge, which is where a managed network's gateway address
belongs and the only sensible answer on a normal node:
curl -k -X POST "$NODE/api/v1/addresses" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"address":"10.20.0.1/24"}'
Name one explicitly — in the path or as "interface" in the body — when the node
has a second bridge or a dedicated interface.
The prefix is required — a bare address is refused rather than guessed. Assuming
/32 where you meant /24 produces an interface that looks correct and cannot
reach its own subnet.
Adding is idempotent, so you can reconcile toward a desired state instead of tracking what you have already done.
An address added here is kept, and put back on the interface when the agent
restarts; the answer says kept. Removing it here forgets it. An address that
cannot be kept is taken off again. A network's host gateway keeps its own address
on the workload bridge.
The way the node is reached is refused. Adding or removing an address is
refused on the management bridge and its card (400) and, with 409, on the
configured uplink, the device a default route leaves through, the device holding
the API's or the cluster's address, and their ports: each carries the address this node is reached on, and a
call that strips it is not recoverable without console access. Reads are allowed
on every interface — seeing the node's own addressing is what a panel needs to
render a network page, and reading cannot strand anything. A read says whether
the interface's addresses can be changed here (managed) and which addresses this
API keeps on it (kept).
An address that would take that way is refused on any interface (409): the
default gateway's address, one of the server's management addresses, the API's or
the cluster's address, another cluster member's address, or one the server already
has on another interface; and an address whose network lies inside or contains the
server's own network, its gateway or a member's address. A single address (a /32,
or a /128) inside the server's own network that is none of these, such as a
failover address, is accepted: it brings no network with it.
To delete, put the address in the path with its prefix URL-escaped:
curl -k -X DELETE "$NODE/api/v1/nics/cnv-user-br0/addresses/10.20.0.1%2F24" \
-H "Authorization: Bearer $TOKEN"
Escaping a slash inside a path segment behaves differently across HTTP clients, proxies and shells, so every one of these is accepted and means the same thing:
| Form | Example |
|---|---|
| Prefix escaped | .../addresses/10.20.0.1%2F24 |
| Dash instead of the slash | .../addresses/10.20.0.1-24 |
| Plain slash | .../addresses/10.20.0.1/24 |
| Query parameter | .../addresses?address=10.20.0.1/24 |
| Bare address | .../addresses/10.20.0.1 |
A bare address carries no prefix, so the prefix is read back off the
interface. That is deliberate: removing 10.20.0.1/32 when the interface holds
10.20.0.1/24 would match nothing and quietly remove nothing. If the address is
not on the interface you get 404 rather than a silent success.
Omitting the interface works here too — DELETE /api/v1/addresses/... defaults
to the workload bridge, the same as POST.
The interfaces on the way the node is reached are refused on every one of these forms.
DHCP scopes
A network's address pool exists from the moment you create it. The DHCP server still will not answer for that subnet until a scope binds serving to the pool. Without one the server has nothing to offer and, per RFC 2131, stays silent — the client retries with no reply, which looks exactly like a broken connection.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/dhcp/scopes | List scopes |
| POST | /api/v1/dhcp/scopes | Bind serving for a subnet to a pool |
| DELETE | /api/v1/dhcp/scopes/{subnet} | Remove a scope |
curl -k -X POST "$NODE/api/v1/dhcp/scopes" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"subnet":"10.20.0.0/24","pool_id":16,"gateway":"10.20.0.1",
"subnet_mask":"255.255.255.0","dns":["1.1.1.1"],"lease_seconds":3600}'
subnet and pool_id are required. Find the pool with
GET /api/v1/ipam/pools — a network's pool carries the network's name. A scope
with no pool is refused, because it would reproduce exactly the silent failure
this exists to prevent. Addresses in gateway, subnet_mask, server_ip and
dns must be valid, or the call is 400.
Two things to plan around:
- A scope added here is kept across restarts. Posting a scope for a subnet that already has one replaces it;
DELETEremoves it for good. Scopes in the node configuration (dhcp_scopes) are applied at every start — deleting one of those here lasts until the next start, and an API scope for the same subnet takes its place.lease_secondscannot be negative (400). - How a request is matched. A request that reaches the node directly is served from the scope whose subnet contains an address the node holds on the interface it arrived on; a relayed request, from the scope whose subnet holds the relay's
giaddr. Leaveserver_iporsubnet_maskout and the node's own address on that subnet and the subnet's own mask are sent. See DHCP & DNS.
Deleting takes the subnet URL-escaped: .../dhcp/scopes/10.20.0.0%2F24. As with
interface addressing, the dash form (10.20.0.0-24), a plain slash and
?subnet=10.20.0.0/24 are all accepted. Any address inside the subnet resolves
to the scope covering it, so 10.20.0.5/24 removes the 10.20.0.0/24 scope.
Reservations, node identity and services
The last of what used to need a shell.
Static DHCP reservations
Pin an address to a MAC so a workload always gets the same one.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/dhcp/reservations | List reservations |
| POST | /api/v1/dhcp/reservations | Pin an address to a MAC |
| DELETE | /api/v1/dhcp/reservations/{mac} | Release one |
curl -k -X POST "$NODE/api/v1/dhcp/reservations" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"mac":"02:ce:0a:4d:00:02","ip":"10.20.0.50","hostname":"db-1"}'
The address is matched to its pool from the address itself, so a reservation does not name a network — and an address outside every configured range is refused rather than stored against nothing.
Node identity
GET /api/v1/node returns the hardware id this node's license and
certificates are bound to, plus its version.
curl -k "$NODE/api/v1/node" -H "Authorization: Bearer $TOKEN"
{ "hardware_id": "b57bd87...", "hardware_id_available": true,
"mode": "gateway", "version": "1.0.0-rc.74" }
mode is always gateway: it is kept only so existing integrations that read it
do not break. There is one kind of node, and every node routes.
This is the value you match a pending activation or certificate request against
before approving it. hardware_id_available is false where the id could not be
derived — on a virtual machine, where the binding inputs are not stable. Show
that rather than presenting the value as an identity.
GET /api/v1/node/features returns the features this node serves, as api_features
lists them on GET /api/v1/node, and the readiness of its cluster: cluster_level
on a node in a cluster (the cluster's level), and placement_ready, true once the
cluster is at level 5 with every member on a version that supports placement,
moves and shared pool declarations. A node in no cluster has no cluster_level, and
its placement_ready is false. Any signed-in operator may read it, including one
without the Sys.Audit privilege that GET /api/v1/node needs for the hardware id.
A tenant key cannot read it.
Services
GET /api/v1/service reports each network service: the operator's switch, the
address it binds, and whether it is actually listening.
curl -k "$NODE/api/v1/service" -H "Authorization: Bearer $TOKEN"
Read-only, deliberately. A switch takes effect at the next agent restart, and an API that flips one without being able to restart the agent would leave you unable to tell whether anything happened. Toggling stays local until the agent can apply it live.
VRF, Geneve and NAT64
VRF devices, Geneve tunnels and NAT64 are created and changed over the API as
well as with the vrf, geneve and nat64 commands. (Plan feature: VXLAN.)
See Networking Overview and
Gateway NAT for what each
does and does not do.
| Method | Path | Purpose |
|---|---|---|
| POST | /api/v1/vrf | Create a VRF ({"name","table"}) — 201 |
| GET / DELETE | /api/v1/vrf/{name} | One VRF; delete it, releasing the members still in it |
| POST | /api/v1/vrf/{name}/members | Attach an interface ({"interface"}) |
| DELETE | /api/v1/vrf/{name}/members/{iface} | Release an interface |
| POST | /api/v1/geneve | Create a tunnel ({"name","vni","remote","port","ttl"}; port 6081 when left out) — 201 |
| GET / DELETE | /api/v1/geneve/{name} | One tunnel; delete it |
| PUT | /api/v1/nat64 | Turn NAT64 on or off, and set its prefix and pool ({"enabled","prefix","pool"}) |
{ "name": "blue", "device": "cnv-vrf-blue", "table": 1001, "interfaces": ["cnv-nic-2"] }
A VRF lists its members as interfaces; a member kept on record but not attached
when the node started is also under not_attached, with the reason, and a VRF
whose table the node's own policy routing has come to use says so under
not_applied. An interface on the way the node is reached, one already part of
something else, a reserved table, one another VRF uses or one the node's own
policy routing uses, a Geneve port the node uses and a second tunnel with the
same VNI, remote and port are 409; a value that is not valid is
400, and an unknown VRF, tunnel or interface 404. Each refusal says what
was refused and that nothing was changed.
PUT /api/v1/nat64 answers the status, with active true only where translation
can work both ways — the forwarding runs on the LAN interface, and the pool
address is the node's own on an interface the forwarding runs on — and reason
saying why when it is not; the change is all or nothing.
Subsystem reads
These subsystems can be read over the API, so a panel can show what a node actually has without shelling in. Each returns the same view its CLI command shows — they call the same manager. The HTTP load balancer, which has its own views and changes over the API, is described under HTTP load balancer (layer 7).
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/vrf | Virtual routing & forwarding devices |
| GET | /api/v1/geneve | Geneve overlay tunnels |
| GET | /api/v1/nat64/status | NAT64 configuration + live bindings |
| GET | /api/v1/plugins | Installed plugins |
| GET | /api/v1/apikeys | Operator API keys — metadata only |
curl -k "$NODE/api/v1/vrf" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/geneve" -H "Authorization: Bearer $TOKEN"
A subsystem that is not running on this node answers 503 naming it, rather than an empty list — "not available here" and "none configured" are different answers and a panel should be able to tell them apart.
/apikeys returns id, label, scope and timestamps, to a caller with
Access.Audit. It never returns key material: a minted key is shown once at
creation and is not recoverable.
Operator keys are API tokens. Each is listed by GET /api/v1/access/tokens
as apikeys@local!<id>, can be narrowed with its permissions and revoked with
DELETE /api/v1/access/users/apikeys@local/tokens/<id> (see
Access control). New ones are minted with
cenvero-str-ctl apikeys mint; for a script, an API token of its own account is
usually the better choice.
Metrics scrape
GET /api/v1/metrics returns the node's metrics in Prometheus text exposition format, behind the same api_token bearer as the rest of the API — so a
Prometheus scrape config authenticates like any other client. It is read-only
(a GET, never blocked by a license freeze) and simply renders already-collected
counters and gauges; it never touches the data plane.
This is distinct from the optional standalone metrics listener (the loopbackmetrics_bind_addr, default127.0.0.1:9090, described in Configuration). Both expose the samestratum_*metric set; this endpoint surfaces it on the authenticated REST API so you can scrape it over the management port without opening a second listener.
curl -k "$NODE/api/v1/metrics" -H "Authorization: Bearer $TOKEN"
Unlike the JSON endpoints, the response is
Content-Type: text/plain; version=0.0.4; charset=utf-8 — the standard Prometheus
exposition body, one # HELP/# TYPE header per metric family followed by its
samples:
# HELP stratum_uptime_seconds Agent uptime in seconds
# TYPE stratum_uptime_seconds gauge
stratum_uptime_seconds 86400
# HELP stratum_active_tasks Active internal tasks
# TYPE stratum_active_tasks gauge
stratum_active_tasks 42
# HELP stratum_lb_forwarded_total Total packets the load balancer sent on to a backend
# TYPE stratum_lb_forwarded_total counter
stratum_lb_forwarded_total 481920
# HELP stratum_firewall_drops_total Total firewall drops
# TYPE stratum_firewall_drops_total counter
stratum_firewall_drops_total{chain="input",reason="acl"} 1204
The exposition covers the families the node already collects: the node's own
figures every 10 seconds (stratum_node_*: CPU busy and I/O wait, load, memory,
swap, filesystems, and bytes per managed interface — see
Monitoring), runtime gauges
(stratum_uptime_seconds, stratum_active_tasks), per-VM byte/packet counters,
per-reason firewall-drop counters, load-balancer packet counters
(stratum_lb_forwarded_total for packets sent on to a backend,
stratum_lb_replies_total for replies sent back to clients), and an alerts-fired
counter.
A minimal Prometheus scrape configuration:
scrape_configs:
- job_name: cenvero-stratum
scheme: https
metrics_path: /api/v1/metrics
authorization:
credentials: <your-api-token>
tls_config:
insecure_skip_verify: true # node cert is privately managed; pin it in production
static_configs:
- targets: ["node.example.com:7070"]
gRPC endpoint
The node also exposes a gRPC endpoint:
<node-ip>:7071
Enable it with cenvero-str-ctl service grpc on. It uses the same TLS certificate as REST/WebSocket and requires the node API token in the
authorization metadata on every call (authorization: Bearer <api-token>). The
node may optionally require a client certificate when configured.
The gRPC port serves the standard gRPC Health Checking protocol
(grpc.health.v1.Health), so load balancers and orchestration systems can probe
node liveness over gRPC. The full management surface is the REST API documented
above — gRPC is for health/liveness probing, not a REST mirror.
grpcurl -H "authorization: Bearer $TOKEN" \
node.example.net:7071 grpc.health.v1.Health/Check
{ "status": "SERVING" }
Server reflection is intentionally disabled; supply the standardgrpc.health.v1descriptor (or use a purpose-built health-probe client). Use the empty service name for overall node health, orcenvero.stratumfor the agent's service.
Every endpoint, ready to paste
One line per endpoint, by area. Set these once and the rest copies straight out:
NODE=https://your-node:7070
TOKEN=your-api-token
Placeholders in braces are yours to fill. Request bodies for the mutating calls are in the sections above; this is the shape and the address, not a replacement for them.
Accounting & billing data
curl -k "$NODE/api/v1/accounting/95th" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/accounting/billing" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/accounting/summary" -H "Authorization: Bearer $TOKEN"
Host addressing (default interface)
curl -k -X POST "$NODE/api/v1/addresses" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
Alerting
curl -k "$NODE/api/v1/alerts" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/alerts" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k "$NODE/api/v1/alerts/conditions" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/alerts/conditions" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/alerts/conditions/{id}" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/alerts/conditions/{id}/actions" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k "$NODE/api/v1/alerts/history" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/alerts/{id}/ack" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X POST "$NODE/api/v1/alerts/{id}/resolve" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/options/notifications" -H "Authorization: Bearer $TOKEN"
curl -k -X PUT "$NODE/api/v1/options/notifications" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"smtp":{},"rev":1}'
curl -k -X POST "$NODE/api/v1/options/notifications/test" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"to":"[email protected]"}'
Operator API keys
curl -k "$NODE/api/v1/apikeys" -H "Authorization: Bearer $TOKEN"
Access control
curl -k "$NODE/api/v1/access/me" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/access/permissions?paths=/vms/vm-1a2b3c4d" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/access/privileges" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/access/roles" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/access/users" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/access/groups" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/access/acl?path=/tenants/t-acme" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/access/tokens" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/access/realms" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/access/users/alice@local/tfa" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/access/groups" -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" -d '{"id":"ops","comment":"On-call operators","members":["alice@local"]}'
curl -k -X POST "$NODE/api/v1/access/roles" -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" -d '{"id":"TenantSupport","privileges":["Tenant.Audit","VM.Audit","VM.PowerMgmt"]}'
curl -k -X DELETE "$NODE/api/v1/access/acl/acl-1f3a9c0d2b4e5f60" -H "Authorization: Bearer $TOKEN"
curl -k -X DELETE "$NODE/api/v1/access/users/alice@local/tokens/ci" -H "Authorization: Bearer $TOKEN"
Audit
curl -k "$NODE/api/v1/audit?limit=50" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/audit/export" -H "Authorization: Bearer $TOKEN" -o audit.jsonl
curl -k "$NODE/api/v1/audit/verify" -H "Authorization: Bearer $TOKEN"
Graph history
curl -k "$NODE/api/v1/rrd/node?timeframe=day" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/rrd/interfaces/cnv-nic-0?timeframe=live" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/rrd/vms/{id}?timeframe=week&cf=max" -H "Authorization: Bearer $TOKEN"
Backups
curl -k "$NODE/api/v1/backups" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/backups" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X POST "$NODE/api/v1/backups/restore" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k "$NODE/api/v1/backups/schedules" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/backups/schedules" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/backups/schedules/{id}" -H "Authorization: Bearer $TOKEN"
Bandwidth & quotas
curl -k "$NODE/api/v1/bandwidth" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/bandwidth" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X POST "$NODE/api/v1/bandwidth/pools" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X POST "$NODE/api/v1/bandwidth/pools/members" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/bandwidth/pools/{id}" -H "Authorization: Bearer $TOKEN"
curl -k -X DELETE "$NODE/api/v1/bandwidth/pools/{id}/members/{mac}" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/bandwidth/quotas" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/bandwidth/quotas" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k "$NODE/api/v1/bandwidth/quotas/{mac}" -H "Authorization: Bearer $TOKEN"
curl -k -X DELETE "$NODE/api/v1/bandwidth/{id}" -H "Authorization: Bearer $TOKEN"
BGP
curl -k -X POST "$NODE/api/v1/bgp/announce" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k "$NODE/api/v1/bgp/neighbors" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/bgp/neighbors" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/bgp/neighbors/{addr}" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/bgp/policy" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/bgp/policy/{dir}" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k "$NODE/api/v1/bgp/prefix-lists" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/bgp/prefix-lists" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k "$NODE/api/v1/bgp/route-maps" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/bgp/route-maps" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k "$NODE/api/v1/bgp/routes" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/bgp/status" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/bgp/withdraw" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k "$NODE/api/v1/bgp/rib?table=local" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/bgp/rpki" -H "Authorization: Bearer $TOKEN"
curl -k -X PUT "$NODE/api/v1/bgp/rpki" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"enabled":true}'
curl -k "$NODE/api/v1/bgp/rpki/validate?prefix=192.0.2.0/24&origin_as=64500" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/bgp/evpn" -H "Authorization: Bearer $TOKEN"
curl -k -X PUT "$NODE/api/v1/bgp/evpn" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"enabled":false}'
curl -k "$NODE/api/v1/bgp/evpn/routes" -H "Authorization: Bearer $TOKEN"
Billing automation
curl -k "$NODE/api/v1/billing/tenants/{id}" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/billing/tenants/{id}/limit" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X POST "$NODE/api/v1/billing/tenants/{id}/resume" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X POST "$NODE/api/v1/billing/tenants/{id}/suspend" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X POST "$NODE/api/v1/billing/tenants/{id}/unlimit" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
NIC bonds
curl -k "$NODE/api/v1/bonds" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/bonds" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/bonds/{id}" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/bonds/{id}" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/bonds/{id}/members" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/bonds/{id}/members/{iface}" -H "Authorization: Bearer $TOKEN"
curl -k -X PUT "$NODE/api/v1/bonds/{id}/mtu" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
Bridges
curl -k "$NODE/api/v1/bridges" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/bridges" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/bridges/{name}" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/bridges/{name}/ports" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/bridges/{name}/ports/{iface}" -H "Authorization: Bearer $TOKEN"
Cluster
curl -k "$NODE/api/v1/cluster" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/cluster/status" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/cluster/state" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/cluster/create" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X POST "$NODE/api/v1/cluster/join-codes" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k "$NODE/api/v1/cluster/join-codes" -H "Authorization: Bearer $TOKEN"
curl -k -X DELETE "$NODE/api/v1/cluster/join-codes/{id}" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/cluster/join-preview" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X POST "$NODE/api/v1/cluster/join-with-code" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X POST "$NODE/api/v1/cluster/leave" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/cluster/members/{id}" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/cluster/members/{id}/rekey" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/cluster/ca/rotate" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/cluster/resources" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/cluster/tasks" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/cluster/audit" -H "Authorization: Bearer $TOKEN"
curl -k -N "$NODE/api/v1/cluster/events" -H "Authorization: Bearer $TOKEN"
# A cluster set up by hand with an earlier version
curl -k -X POST "$NODE/api/v1/cluster/join" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
# 501 — see Not implemented
curl -k -X POST "$NODE/api/v1/cluster/profile" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k "$NODE/api/v1/cluster/update" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/cluster/update" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
Configuration
curl -k "$NODE/api/v1/config/export" -H "Authorization: Bearer $TOKEN" -o config-export.json
Container networking
curl -k "$NODE/api/v1/containers" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/containers/attach" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k "$NODE/api/v1/containers/{id}" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/containers/{id}/detach" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
Dashboard
curl -k "$NODE/api/v1/dashboard" -H "Authorization: Bearer $TOKEN"
DHCP
curl -k "$NODE/api/v1/dhcp/leases" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/dhcp/reservations" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/dhcp/reservations" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/dhcp/reservations/{mac}" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/dhcp/scopes" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/dhcp/scopes" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/dhcp/scopes/{subnet}" -H "Authorization: Bearer $TOKEN"
DNS
curl -k "$NODE/api/v1/dns/dnssec/{zone}" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/dns/records" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/dns/records" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X POST "$NODE/api/v1/dns/records/batch" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/dns/records/{id}" -H "Authorization: Bearer $TOKEN"
curl -k -X PUT "$NODE/api/v1/dns/records/{id}" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"name":"db","type":"A","value":"10.20.0.11"}'
curl -k "$NODE/api/v1/dns/zones" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/dns/zones" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/dns/zones/{id}" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/dns/forwarders" -H "Authorization: Bearer $TOKEN"
curl -k -X PUT "$NODE/api/v1/dns/forwarders" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"forwarders":["1.1.1.1"]}'
Endpoint index
curl -k "$NODE/api/v1/docs" -H "Authorization: Bearer $TOKEN"
Event stream
curl -k -N "$NODE/api/v1/events" -H "Authorization: Bearer $TOKEN"
curl -k -N "$NODE/api/v1/events" -H "Authorization: Bearer $TOKEN" -H "Last-Event-ID: {node}:{seq}"
Nodes and resources
curl -k "$NODE/api/v1/nodes" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/resources" -H "Authorization: Bearer $TOKEN"
# Any route of another cluster member: /api/v1/nodes/{node}/ in front of its path
# (a backup target's key export and import are not passed on: call them on the node that holds the target, without the prefix)
curl -k "$NODE/api/v1/nodes/{node}/vms" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/resources?tag=prod" -H "Authorization: Bearer $TOKEN"
Floating IPs
curl -k "$NODE/api/v1/float" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/float" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/float/{id}" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/float/{id}" -H "Authorization: Bearer $TOKEN"
Flow tracking
curl -k "$NODE/api/v1/flows" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/flows/export" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/flows/stats" -H "Authorization: Bearer $TOKEN"
Port forwarding
curl -k "$NODE/api/v1/forward" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/forward" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/forward/{id}" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/forward/{id}" -H "Authorization: Bearer $TOKEN"
Gateway & NAT
curl -k -X POST "$NODE/api/v1/gateway/failback" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X POST "$NODE/api/v1/gateway/failover" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k "$NODE/api/v1/gateway/snat" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/gateway/snat" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/gateway/snat/{id}" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/gateway/status" -H "Authorization: Bearer $TOKEN"
Geneve tunnels
curl -k "$NODE/api/v1/geneve" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/geneve" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"name":"east","vni":5001,"remote":"198.51.100.20"}'
curl -k "$NODE/api/v1/geneve/{name}" -H "Authorization: Bearer $TOKEN"
curl -k -X DELETE "$NODE/api/v1/geneve/{name}" -H "Authorization: Bearer $TOKEN"
Self-healing
curl -k "$NODE/api/v1/heal" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/heal/check" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
Health
curl -k "$NODE/api/v1/health" -H "Authorization: Bearer $TOKEN"
Address pools
curl -k -X POST "$NODE/api/v1/ipam/allocate" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k "$NODE/api/v1/ipam/allocations" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/ipam/pools" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/ipam/pools" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/ipam/pools/{id}" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/ipam/release" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
Layer-7 load balancer
curl -k "$NODE/api/v1/l7lb/frontends" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/l7lb/pools" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/l7lb/status" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/l7lb/pools" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/l7lb/pools/{name}" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/l7lb/pools/{name}/backends" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/l7lb/pools/{name}/backends" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/l7lb/pools/{name}/backends/{backend}" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/l7lb/frontends" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/l7lb/frontends/{name}" -H "Authorization: Bearer $TOKEN"
Layer-4 load balancer
curl -k "$NODE/api/v1/lb" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/lb" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/lb/{id}" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/lb/{id}" -H "Authorization: Bearer $TOKEN"
curl -k -X PUT "$NODE/api/v1/lb/{id}" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}' # 501
curl -k -X POST "$NODE/api/v1/lb/{id}/backends" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/lb/{id}/backends/{bid}" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/lb/{id}/backends/{bid}/health" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"healthy":false}'
curl -k -X PUT "$NODE/api/v1/lb/{id}/backends/{bid}/admin" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"state":"out"}'
License
curl -k "$NODE/api/v1/license" -H "Authorization: Bearer $TOKEN"
MAC bindings
curl -k "$NODE/api/v1/macbind" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/macbind" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/macbind/{mac}" -H "Authorization: Bearer $TOKEN"
Metrics
curl -k "$NODE/api/v1/metrics" -H "Authorization: Bearer $TOKEN"
NAT64
curl -k "$NODE/api/v1/nat64/status" -H "Authorization: Bearer $TOKEN"
curl -k -X PUT "$NODE/api/v1/nat64" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"enabled":false}'
Networks & endpoints
curl -k "$NODE/api/v1/networks" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/networks" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/networks/{id}" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/networks/{id}" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/networks/{id}/attach" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k "$NODE/api/v1/networks/{id}/endpoints" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/networks/{id}/endpoints/{eid}/detach" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X PUT "$NODE/api/v1/networks/{id}/endpoints/{eid}/mac" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X PUT "$NODE/api/v1/networks/{id}/host-gateway" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/networks/{id}/host-gateway" -H "Authorization: Bearer $TOKEN"
Routed public addresses
curl -k "$NODE/api/v1/routed-addresses" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/routed-addresses" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/routed-addresses/{id}" -H "Authorization: Bearer $TOKEN"
Interfaces & addressing
curl -k "$NODE/api/v1/nics" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/nics/{iface}/addresses" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/nics/{iface}/addresses" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/nics/{iface}/addresses/{cidr}" -H "Authorization: Bearer $TOKEN"
Node identity
curl -k "$NODE/api/v1/node" -H "Authorization: Bearer $TOKEN"
Plugins
curl -k "$NODE/api/v1/plugins" -H "Authorization: Bearer $TOKEN"
Routing
curl -k "$NODE/api/v1/routes" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/routes" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k "$NODE/api/v1/routes/rules" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/routes/rules" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/routes/rules/{id}" -H "Authorization: Bearer $TOKEN"
curl -k -X DELETE "$NODE/api/v1/routes/{id}" -H "Authorization: Bearer $TOKEN"
Firewall rules
curl -k "$NODE/api/v1/rules" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/rules" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X POST "$NODE/api/v1/rules/batch" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/rules/{id}" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/rules/{id}" -H "Authorization: Bearer $TOKEN"
curl -k -X PUT "$NODE/api/v1/rules/{id}" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k "$NODE/api/v1/rules/default" -H "Authorization: Bearer $TOKEN"
curl -k -X PUT "$NODE/api/v1/rules/default" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"default_action":"deny"}'
curl -k "$NODE/api/v1/firewall/schedules" -H "Authorization: Bearer $TOKEN"
curl -k -X PUT "$NODE/api/v1/firewall/schedules/{rule}" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"days":["mon"],"start":"08:00","end":"18:00"}'
curl -k -X DELETE "$NODE/api/v1/firewall/schedules/{rule}" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/firewall/connlimit" -H "Authorization: Bearer $TOKEN"
curl -k -X PUT "$NODE/api/v1/firewall/connlimit" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"max_per_source":200}'
curl -k -X DELETE "$NODE/api/v1/firewall/connlimit" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/firewall/conntrack?limit=100" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/firewall/conntrack/flush" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/firewall/blocklist" -H "Authorization: Bearer $TOKEN"
curl -k -X DELETE "$NODE/api/v1/firewall/blocklist/{address}" -H "Authorization: Bearer $TOKEN"
Services
curl -k "$NODE/api/v1/service" -H "Authorization: Bearer $TOKEN"
Status
curl -k "$NODE/api/v1/status" -H "Authorization: Bearer $TOKEN"
Tenants
curl -k "$NODE/api/v1/tenant" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/tenant" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/tenant/{id}" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/tenant/{id}" -H "Authorization: Bearer $TOKEN"
curl -k -X PUT "$NODE/api/v1/tenant/{id}" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k "$NODE/api/v1/tenant/{id}/keys" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/tenant/{id}/keys" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/tenant/{id}/keys/{kid}" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/tenant/{id}/quota" -H "Authorization: Bearer $TOKEN"
curl -k -X PUT "$NODE/api/v1/tenant/{id}/quota" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k "$NODE/api/v1/tenant/{id}/tasks" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/tenant/{id}/tasks/{tid}" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/tenant/{id}/resources" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/tenant/{id}/nodes" -H "Authorization: Bearer $TOKEN"
System log
curl -k "$NODE/api/v1/syslog?lines=100" -H "Authorization: Bearer $TOKEN"
Tasks
curl -k "$NODE/api/v1/tasks" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/tasks/{id}" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/tasks/{id}/log" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/tasks/{id}/cancel" -H "Authorization: Bearer $TOKEN"
TLS
curl -k "$NODE/api/v1/tls/pubkey" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/tls" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/tls/domains" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"domain":"node1.example.net"}'
curl -k -X DELETE "$NODE/api/v1/tls/domains/{domain}" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/tls/request" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/tls/pull" -H "Authorization: Bearer $TOKEN"
Tags, notes and the brand
curl -k "$NODE/api/v1/annotations/vm/{id}" -H "Authorization: Bearer $TOKEN"
curl -k -X PUT "$NODE/api/v1/annotations/vm/{id}" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"tags":["prod"],"notes":"","rev":0}'
curl -k "$NODE/api/v1/annotations/network/{id}" -H "Authorization: Bearer $TOKEN"
curl -k -X PUT "$NODE/api/v1/annotations/network/{id}" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"tags":[],"notes":"","rev":0}'
curl -k "$NODE/api/v1/annotations/volume/{id}" -H "Authorization: Bearer $TOKEN"
curl -k -X PUT "$NODE/api/v1/annotations/volume/{id}" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"tags":[],"notes":"","rev":0}'
curl -k "$NODE/api/v1/annotations/image/{id}" -H "Authorization: Bearer $TOKEN"
curl -k -X PUT "$NODE/api/v1/annotations/image/{id}" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"tags":[],"notes":"","rev":0}'
curl -k "$NODE/api/v1/annotations/tenant/{id}" -H "Authorization: Bearer $TOKEN"
curl -k -X PUT "$NODE/api/v1/annotations/tenant/{id}" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"tags":[],"notes":"","rev":0}'
curl -k "$NODE/api/v1/annotations/node" -H "Authorization: Bearer $TOKEN"
curl -k -X PUT "$NODE/api/v1/annotations/node" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"tags":[],"notes":"","rev":0}'
curl -k "$NODE/api/v1/options/brand" -H "Authorization: Bearer $TOKEN"
curl -k -X PUT "$NODE/api/v1/options/brand" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"rev":1}'
curl -k -X PUT "$NODE/api/v1/options/brand/logo" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"type":"image/png","data":"<base64>"}'
curl -k -X DELETE "$NODE/api/v1/options/brand/logo" -H "Authorization: Bearer $TOKEN"
curl -k -X PUT "$NODE/api/v1/options/brand/favicon" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"type":"image/png","data":"<base64>"}'
curl -k -X DELETE "$NODE/api/v1/options/brand/favicon" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/options/tags" -H "Authorization: Bearer $TOKEN"
curl -k -X PUT "$NODE/api/v1/options/tags" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"colours":{},"rev":0}'
Topology
curl -k "$NODE/api/v1/topology" -H "Authorization: Bearer $TOKEN" # 501 — see Not implemented
VLAN lockdown
curl -k "$NODE/api/v1/vlan" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/vlan" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/vlan/{id}" -H "Authorization: Bearer $TOKEN"
VRF devices
curl -k "$NODE/api/v1/vrf" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/vrf" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"name":"blue","table":1001}'
curl -k "$NODE/api/v1/vrf/{name}" -H "Authorization: Bearer $TOKEN"
curl -k -X DELETE "$NODE/api/v1/vrf/{name}" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/vrf/{name}/members" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"interface":"cnv-nic-2"}'
curl -k -X DELETE "$NODE/api/v1/vrf/{name}/members/{iface}" -H "Authorization: Bearer $TOKEN"
VXLAN overlays
curl -k "$NODE/api/v1/vxlan/fdb" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/vxlan/networks" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/vxlan/networks" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/vxlan/networks/{vni}" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/vxlan/networks/{vni}/peers" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/vxlan/networks/{vni}/peers" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/vxlan/networks/{vni}/peers/{host}" -H "Authorization: Bearer $TOKEN"
Updates
curl -k "$NODE/api/v1/update" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/update/check" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/update/apply" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X POST "$NODE/api/v1/update/rollback" -H "Authorization: Bearer $TOKEN"
Webhooks
curl -k "$NODE/api/v1/webhooks" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/webhooks" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
curl -k -X DELETE "$NODE/api/v1/webhooks/{id}" -H "Authorization: Bearer $TOKEN"
curl -k "$NODE/api/v1/webhooks/{id}" -H "Authorization: Bearer $TOKEN"
curl -k -X POST "$NODE/api/v1/webhooks/{id}/test" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'
Feedback
Found a gap, an inaccuracy, or something you wish this API did? We want to hear it.
Tell us through the contact form on the website. Please include the
agent version
(cenvero-str-ctl version) and the endpoint in question.
See also
- CLI Reference — the same managers from the local
cenvero-str-ctlcommand line. - Configuration — node config, ports, and the API settings.
- Clustering — forming a cluster and managing every node from any of them.
- Licensing — activation, renewal, and the enforcement states.