Référence#
Cette page est générée depuis api/agent.yaml, à la racine du dépôt. C’est la source unique
du contrat : en cas d’écart avec le reste de la documentation, c’est elle qui fait foi.
- GET /vpcs#
List all VPCs
Example request:
GET /vpcs HTTP/1.1 Host: example.com
- Codes de statut:
200 OK –
List of VPCs
Example response:
HTTP/1.1 200 OK Content-Type: application/json [ { "name": "string", "state": "creating", "cidr": "string", "l3vni": 1 } ]
Internal server error
Example response:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "error": "string" }
- POST /vpcs#
Create a VPC
Example request:
POST /vpcs HTTP/1.1 Host: example.com Content-Type: application/json { "name": "string", "cidr": "string", "l3vni": 1 }
- Codes de statut:
VPC creation accepted
Example response:
HTTP/1.1 202 Accepted Content-Type: application/json { "name": "string", "state": "creating", "cidr": "string", "l3vni": 1 }
Missing required field, invalid request body, invalid CIDR, or l3vni out of range
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
VPC already exists, l3vni already used by another VPC, or l3vni requested on an agent without a bgp section
Example response:
HTTP/1.1 409 Conflict Content-Type: application/json { "error": "string" }
Internal server error
Example response:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "error": "string" }
- GET /vpcs/{name}#
Get VPC status and info
- Paramètres:
name (string) – Resource name
Example request:
GET /vpcs/{name} HTTP/1.1 Host: example.com
- Codes de statut:
200 OK –
VPC found
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "name": "string", "state": "creating", "cidr": "string", "l3vni": 1 }
Resource not found
Example response:
HTTP/1.1 404 Not Found Content-Type: application/json { "error": "string" }
Internal server error
Example response:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "error": "string" }
- DELETE /vpcs/{name}#
Delete a VPC
- Paramètres:
name (string) – Resource name
- Codes de statut:
VPC deletion accepted
Example response:
HTTP/1.1 202 Accepted Content-Type: application/json { "name": "string", "state": "creating", "cidr": "string", "l3vni": 1 }
Resource not found
Example response:
HTTP/1.1 404 Not Found Content-Type: application/json { "error": "string" }
VPC not deletable — only running or error states can be deleted, all its subnets must be deleted or deleting (subnets still deleting are awaited by the asynchronous deletion), and its NAT gateway, if any, must be deleted first
Example response:
HTTP/1.1 409 Conflict Content-Type: application/json { "error": "string" }
Internal server error
Example response:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "error": "string" }
- GET /vms#
List all VMs
Example request:
GET /vms HTTP/1.1 Host: example.com
- Codes de statut:
200 OK –
List of VMs
Example response:
HTTP/1.1 200 OK Content-Type: application/json [ { "name": "string", "state": "creating", "metadata_port": "string", "memory": 1, "cpus": 1, "interfaces": [ { "name": "string", "subnet": "string", "ip": "string", "mac": "string", "primary": true, "dhcp_server": true, "floating_ip": { "name": "string", "ip": "string", "state": "creating" } } ], "storage": [ { "path": "string", "dev": "string" } ], "uefi": true } ]
Internal server error
Example response:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "error": "string" }
- POST /vms#
Start a VM
Example request:
POST /vms HTTP/1.1 Host: example.com Content-Type: application/json { "name": "string", "memory": 1, "cpus": 1, "metadata": { "password": "string", "sshkey": "string", "user_data": "c3RyaW5n" }, "interfaces": [ { "name": "string", "subnet": "string", "ip": "string", "mac": "string", "primary": true, "dhcp_server": true } ], "storage": [ { "path": "string", "dev": "string" } ], "uefi": true }
- Codes de statut:
VM start accepted
Example response:
HTTP/1.1 202 Accepted Content-Type: application/json { "name": "string", "state": "creating", "metadata_port": "string", "memory": 1, "cpus": 1, "interfaces": [ { "name": "string", "subnet": "string", "ip": "string", "mac": "string", "primary": true, "dhcp_server": true, "floating_ip": { "name": "string", "ip": "string", "state": "creating" } } ], "storage": [ { "path": "string", "dev": "string" } ], "uefi": true }
Missing required field or invalid request body
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
VM already exists
Example response:
HTTP/1.1 409 Conflict Content-Type: application/json { "error": "string" }
Subnet not found, or not in creating/running state; or an interface IP outside the subnet CIDR, equal to its network or broadcast address, or reserved by the subnet (interface_ip, relay_ip, gateway)
Example response:
HTTP/1.1 422 Unprocessable Content Content-Type: application/json { "error": "string" }
Internal server error
Example response:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "error": "string" }
- GET /vms/{name}#
Get VM status and info
- Paramètres:
name (string) – Resource name
Example request:
GET /vms/{name} HTTP/1.1 Host: example.com
- Codes de statut:
200 OK –
VM found
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "name": "string", "state": "creating", "metadata_port": "string", "memory": 1, "cpus": 1, "interfaces": [ { "name": "string", "subnet": "string", "ip": "string", "mac": "string", "primary": true, "dhcp_server": true, "floating_ip": { "name": "string", "ip": "string", "state": "creating" } } ], "storage": [ { "path": "string", "dev": "string" } ], "uefi": true }
Resource not found
Example response:
HTTP/1.1 404 Not Found Content-Type: application/json { "error": "string" }
Internal server error
Example response:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "error": "string" }
- DELETE /vms/{name}#
Stop a VM
- Paramètres:
name (string) – Resource name
- Codes de statut:
VM stop accepted
Example response:
HTTP/1.1 202 Accepted Content-Type: application/json { "name": "string", "state": "creating", "metadata_port": "string", "memory": 1, "cpus": 1, "interfaces": [ { "name": "string", "subnet": "string", "ip": "string", "mac": "string", "primary": true, "dhcp_server": true, "floating_ip": { "name": "string", "ip": "string", "state": "creating" } } ], "storage": [ { "path": "string", "dev": "string" } ], "uefi": true }
Resource not found
Example response:
HTTP/1.1 404 Not Found Content-Type: application/json { "error": "string" }
VM not stoppable — only running or error states can be stopped, and its floating IPs must be deleted first
Example response:
HTTP/1.1 409 Conflict Content-Type: application/json { "error": "string" }
Internal server error
Example response:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "error": "string" }
- GET /subnets#
List all subnets
Example request:
GET /subnets HTTP/1.1 Host: example.com
- Codes de statut:
200 OK –
List of subnets
Example response:
HTTP/1.1 200 OK Content-Type: application/json [ { "name": "string", "state": "creating", "vpc": "string", "mode": "vxlan", "vxlan_id": 1, "local_iface": "string", "interface_ip": "string", "relay_ip": "string", "cidr": "string", "default_route": true, "gateway": "string" } ]
Internal server error
Example response:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "error": "string" }
- POST /subnets#
Create a subnet
Example request:
POST /subnets HTTP/1.1 Host: example.com Content-Type: application/json { "name": "string", "vpc": "string", "mode": "vxlan", "vxlan_id": 1, "iface_type": "string", "interface_ip": "string", "cidr": "string", "default_route": true, "gateway": "string" }
- Codes de statut:
Subnet creation accepted
Example response:
HTTP/1.1 202 Accepted Content-Type: application/json { "name": "string", "state": "creating", "vpc": "string", "mode": "vxlan", "vxlan_id": 1, "local_iface": "string", "interface_ip": "string", "relay_ip": "string", "cidr": "string", "default_route": true, "gateway": "string" }
Missing required field; interface_ip missing on a bridge or public_ip subnet, or supplied on a vxlan subnet (it is computed); default_route true without gateway on a vxlan or public_ip subnet
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
Subnet already exists
Example response:
HTTP/1.1 409 Conflict Content-Type: application/json { "error": "string" }
Unknown mode; parent VPC does not exist or is not ready; invalid CIDR, or a vxlan CIDR smaller than /29
Example response:
HTTP/1.1 422 Unprocessable Content Content-Type: application/json { "error": "string" }
Internal server error
Example response:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "error": "string" }
- GET /subnets/{name}#
Get subnet status and info
- Paramètres:
name (string) – Resource name
Example request:
GET /subnets/{name} HTTP/1.1 Host: example.com
- Codes de statut:
200 OK –
Subnet found
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "name": "string", "state": "creating", "vpc": "string", "mode": "vxlan", "vxlan_id": 1, "local_iface": "string", "interface_ip": "string", "relay_ip": "string", "cidr": "string", "default_route": true, "gateway": "string" }
Resource not found
Example response:
HTTP/1.1 404 Not Found Content-Type: application/json { "error": "string" }
Internal server error
Example response:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "error": "string" }
- DELETE /subnets/{name}#
Delete a subnet
- Paramètres:
name (string) – Resource name
- Codes de statut:
Subnet deletion accepted
Example response:
HTTP/1.1 202 Accepted Content-Type: application/json { "name": "string", "state": "creating", "vpc": "string", "mode": "vxlan", "vxlan_id": 1, "local_iface": "string", "interface_ip": "string", "relay_ip": "string", "cidr": "string", "default_route": true, "gateway": "string" }
Resource not found
Example response:
HTTP/1.1 404 Not Found Content-Type: application/json { "error": "string" }
Subnet not deletable — only running or error states can be deleted, and every VM with an interface on it must be deleted or deleting; VMs still deleting are awaited by the asynchronous deletion
Example response:
HTTP/1.1 409 Conflict Content-Type: application/json { "error": "string" }
Internal server error
Example response:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "error": "string" }
- GET /nat-gateways#
List all NAT gateways of this agent
Example request:
GET /nat-gateways HTTP/1.1 Host: example.com
- Codes de statut:
200 OK –
List of NAT gateways
Example response:
HTTP/1.1 200 OK Content-Type: application/json [ { "name": "string", "state": "creating", "vpc": "string", "ip": "string", "gateway": "string" } ]
Internal server error
Example response:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "error": "string" }
- POST /nat-gateways#
Create the NAT gateway of a VPC on this agent
Gives the VMs of a VPC without a public IP an Internet exit through this host. The gateway owns the given public IP on the public bridge (interfaces.internet) and announces a type-5 default route in the VRF of the VPC. Only VPCs created by this version or later route their default traffic to the VRF, and can use it. To move the gateway, delete it on the old host if it answers, then create it on the new one.
Example request:
POST /nat-gateways HTTP/1.1 Host: example.com Content-Type: application/json { "name": "string", "vpc": "string", "ip": "string", "gateway": "string" }
- Codes de statut:
NAT gateway creation accepted
Example response:
HTTP/1.1 202 Accepted Content-Type: application/json { "name": "string", "state": "creating", "vpc": "string", "ip": "string", "gateway": "string" }
Missing required field, invalid request body, ip without prefix length or not IPv4, or gateway not IPv4
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
NAT gateway already exists, VPC unknown on this agent or not running, VPC without l3vni, or VPC that already has a NAT gateway on this agent
Example response:
HTTP/1.1 409 Conflict Content-Type: application/json { "error": "string" }
Internal server error
Example response:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "error": "string" }
- GET /nat-gateways/{name}#
Get NAT gateway status and info
- Paramètres:
name (string) – Resource name
Example request:
GET /nat-gateways/{name} HTTP/1.1 Host: example.com
- Codes de statut:
200 OK –
NAT gateway found
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "name": "string", "state": "creating", "vpc": "string", "ip": "string", "gateway": "string" }
Resource not found
Example response:
HTTP/1.1 404 Not Found Content-Type: application/json { "error": "string" }
Internal server error
Example response:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "error": "string" }
- DELETE /nat-gateways/{name}#
Delete a NAT gateway
- Paramètres:
name (string) – Resource name
- Codes de statut:
NAT gateway deletion accepted
Example response:
HTTP/1.1 202 Accepted Content-Type: application/json { "name": "string", "state": "creating", "vpc": "string", "ip": "string", "gateway": "string" }
Resource not found
Example response:
HTTP/1.1 404 Not Found Content-Type: application/json { "error": "string" }
NAT gateway not deletable — only running or error states can be deleted
Example response:
HTTP/1.1 409 Conflict Content-Type: application/json { "error": "string" }
Internal server error
Example response:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "error": "string" }
- GET /floating-ips#
List all floating IPs of this agent
Example request:
GET /floating-ips HTTP/1.1 Host: example.com
- Codes de statut:
200 OK –
List of floating IPs
Example response:
HTTP/1.1 200 OK Content-Type: application/json [ { "name": "string", "state": "creating", "vm": "string", "interface": "string", "ip": "string", "gateway": "string" } ]
Internal server error
Example response:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "error": "string" }
- POST /floating-ips#
Attach a floating IP to an interface of a VM of this agent
Makes an interface of a VM reachable through a public IP it does not carry: stateless 1:1 translation in the netns of the VPC, on the host of the VM, the public IP answering ARP on the public bridge (interfaces.internet). The VM leaves through its floating IP, even in a VPC with a NAT gateway. To move it with the VM, delete it on the old host, then create it on the new one. Attach and detach without touching the VM.
Example request:
POST /floating-ips HTTP/1.1 Host: example.com Content-Type: application/json { "name": "string", "vm": "string", "interface": "string", "ip": "string", "gateway": "string" }
- Codes de statut:
Floating IP creation accepted
Example response:
HTTP/1.1 202 Accepted Content-Type: application/json { "name": "string", "state": "creating", "vm": "string", "interface": "string", "ip": "string", "gateway": "string" }
Missing required field, invalid request body, ip without prefix length or not IPv4, or gateway not IPv4
Example response:
HTTP/1.1 400 Bad Request Content-Type: application/json { "error": "string" }
Floating IP already exists, VM unknown on this agent or not running, no interface of that name on the VM, interface on a public_ip subnet (it carries its public IP itself), interface that already has a floating IP, or public IP already used by another floating IP of this agent
Example response:
HTTP/1.1 409 Conflict Content-Type: application/json { "error": "string" }
Internal server error
Example response:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "error": "string" }
- GET /floating-ips/{name}#
Get floating IP status and info
- Paramètres:
name (string) – Resource name
Example request:
GET /floating-ips/{name} HTTP/1.1 Host: example.com
- Codes de statut:
200 OK –
Floating IP found
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "name": "string", "state": "creating", "vm": "string", "interface": "string", "ip": "string", "gateway": "string" }
Resource not found
Example response:
HTTP/1.1 404 Not Found Content-Type: application/json { "error": "string" }
Internal server error
Example response:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "error": "string" }
- DELETE /floating-ips/{name}#
Detach and delete a floating IP
- Paramètres:
name (string) – Resource name
- Codes de statut:
Floating IP deletion accepted
Example response:
HTTP/1.1 202 Accepted Content-Type: application/json { "name": "string", "state": "creating", "vm": "string", "interface": "string", "ip": "string", "gateway": "string" }
Resource not found
Example response:
HTTP/1.1 404 Not Found Content-Type: application/json { "error": "string" }
Floating IP not deletable — only running or error states can be deleted
Example response:
HTTP/1.1 409 Conflict Content-Type: application/json { "error": "string" }
Internal server error
Example response:
HTTP/1.1 500 Internal Server Error Content-Type: application/json { "error": "string" }