Request Body

Response

200 Admin user with api_token

Login attempts (success and failure) are written to the ops log.

Stateless. Records a logout entry in the ops log for the admin identified by X-Admin-Token. The GUI calls this before clearing the session cookie.

Response

204 No content

Generates a fresh API token for the calling admin. The old token stops working immediately on success — single-token rotation, no overlap window. The response body contains the new plaintext token, and the GUI auth panel updates in place; copy it from there any time.

Authentication: requires X-Admin-Token of the admin being rotated.

GUI behavior: the cloud-manager GUI resolves the admin token from the database on every request, so rotation is transparent — no pod restart, no dropped session. Update state/.credentials.json on the install host afterward so installer/update scripts keep working.

Response

200 {"username": "...", "api_token": "..."}

Request Body

Login attempts (success and failure) are written to the ops log.

Response

200 {"id": "...", "name": "...", "api_token": "..."}

Stateless. Records a logout entry in the ops log for the tenant identified by X-API-Token. Called by the cloud-user GUI before clearing the session cookie.

Response

204 No content

Generates a fresh API token for the tenant. The old token stops working immediately on success — single-token rotation, no overlap window. The response body contains the new plaintext token, and the GUI auth panel updates in place; copy it from there any time.

Authentication: either X-Admin-Token (operator override) or X-API-Token of the tenant being rotated (self-service). Tenants can only rotate their own token.

Response

200 {"id": "...", "name": "...", "api_token": "..."}

Request Body

Response

200 Array of tenants

Response

200 Tenant object with VPCs, pods, tunnels, and pod status

Response

204 Tenant deleted (cascades to all resources)

Request Body

Response

200 Array of domains

Request Body

Response

200 Provider configuration

Request Body

Example

curl -k -X POST $API_URL/vpcs \
  -H "X-Auth-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "YOUR_TENANT_ID",
    "token": "YOUR_TOKEN",
    "name": "production",
    "enable_internet": true
  }'

Response

200 Array of VPCs

Response

204 VPC deleted (cascades to subnets and pods)

Request Body

Example

curl -k -X POST $API_URL/subnets \
  -H "X-Auth-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "YOUR_TENANT_ID",
    "token": "YOUR_TOKEN",
    "vpc_id": "VPC_ID",
    "name": "web-tier",
    "cidr": "10.100.1.0/24",
    "gateway_ip": "10.100.1.1"
  }'

Response

200 Array of subnets

Query Parameters

Response

200 Rules in evaluation order, plus the three implied rules

{
  "vpc_id": "vpc-uuid",
  "rules": [
    {
      "id": "rule-uuid",
      "name": "Allow internal traffic",
      "direction": "ingress",
      "action": "allow",
      "priority": 2000,
      "protocol": "all",
      "ports": null,
      "remote_type": "vpc",
      "remote_vpc_id": "vpc-uuid",
      "target_type": "vpc",
      "enabled": true
    }
  ],
  "implied": [
    {"key": "implied-allow-infrastructure", "direction": "ingress", "action": "allow"},
    {"key": "implied-allow-egress", "direction": "egress", "action": "allow"},
    {"key": "implied-deny-ingress", "direction": "ingress", "action": "deny"}
  ],
  "applied": true,
  "apply_error": null
}

Notes: every new VPC is seeded with one ordinary "Allow internal traffic" rule (priority 2000), editable and deletable like any other rule. A rule with enabled: false is kept but not enforced. A rule whose remote VPC, subnet, or pods have since been deleted reports remote_vpc_missing/target_missing and is skipped by enforcement.

Response

200 One rule object (same shape as the entries in rules above)

404 Rule does not exist or belongs to another tenant

Request Body

Example

curl -k -X POST $API_URL/security-rules \
  -H "X-Auth-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vpc_id": "VPC_ID",
    "name": "allow-https-from-internet",
    "direction": "ingress",
    "action": "allow",
    "priority": 100,
    "protocol": "tcp",
    "ports": "443",
    "remote_type": "cidr",
    "remote_cidr": "0.0.0.0/0",
    "target_type": "vpc"
  }'

Response

201 Rule created; rule carries the full rule object

{
  "rule": {
    "id": "rule-uuid",
    "name": "allow-https-from-internet",
    "priority": 100,
    "enabled": true
  },
  "applied": true,
  "apply_error": null
}

404 vpc_id does not exist or belongs to another tenant

409 The VPC already has the maximum of 200 rules

422 Validation failure; detail names the field: {"field": ..., "message": ...}. Includes IPv6 CIDRs (rules are IPv4-only), ports on a portless protocol, or referencing a subnet/pod/VPC that is not yours or not in this VPC.

Partial update — only the fields present in the body change. Accepts any subset of the create parameters except vpc_id (a rule cannot move between VPCs). Every rule is editable, the seeded internal rule included.

Example

curl -k -X PATCH $API_URL/security-rules/RULE_ID \
  -H "X-Auth-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"priority": 50, "enabled": false}'

Notes: when changing remote_type or target_type, send the matching companion field(s) in the same request (e.g. remote_type: "cidr" with remote_cidr); stale companions from the previous shape are cleared automatically. Ports are re-validated whenever ports or protocol changes.

Response

200 Same shape as the create response (rule, applied, apply_error)

404 Rule does not exist or belongs to another tenant

422 Validation failure; detail is {"field": ..., "message": ...}

Response

200 With a body (not 204), so it can report whether the change reached the network

{"rule": null, "applied": true, "apply_error": null}

404 Rule does not exist or belongs to another tenant

Note: no rule is protected, and a deleted rule stays deleted — nothing re-seeds it.

Rewrites the priorities of every rule in one VPC in a single call. rule_ids must list that VPC's rules exactly once each, in the desired evaluation order — a partial list is rejected. Priorities are re-issued as 10, 20, 30, ..., leaving room to slot a rule in between later.

Request Body

Example

curl -k -X POST $API_URL/security-rules/reorder \
  -H "X-Auth-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vpc_id": "VPC_ID",
    "rule_ids": ["RULE_ID_2", "RULE_ID_1", "RULE_ID_3"]
  }'

Response

200 Same shape as the list response, with the new priorities

404 vpc_id is not yours, or a listed rule is not in this VPC

422 A rule is listed more than once, or the list is missing some of the VPC's rules

Request Body

Notes: For replicas, Circloud creates one VIP service that load-balances across all replicas. Auto-scaling implies auto_healing, and the minimum replica count is always 2. Live status data is available in the admin /tenants/{tenant_id} response.

Example

curl -k -X POST $API_URL/pods \
  -H "X-Auth-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "YOUR_TENANT_ID",
    "token": "YOUR_TOKEN",
    "vpc_id": "VPC_ID",
    "subnet_id": "SUBNET_ID",
    "name": "web-server",
    "container_image": "nginx:latest",
    "replica_count": 2,
    "service_port": 80,
    "external_access": true,
    "external_inbound": true,
    "auto_scaling": true,
    "autoscale_max_replicas": 6,
    "autoscale_cpu_target_millicores": 250,
    "env_vars": {
      "DATABASE_URL": "postgres://app:pw@db:5432/app",
      "LOG_LEVEL": "info"
    }
  }'

env_vars

Optional. Container environment variables as a name → value map (strings only). Stored encrypted at rest (Fernet), safe for DB passwords and API keys. Update later via PATCH /pods/{pod_id}/config.

Response

200 Pod object with updated replica_count

Note: Adds a single replica and updates the logical pod's replica_count. Not available when auto_scaling is enabled.

Response

200 Pod object with updated replica_count

Note: Removes a single replica (minimum 1). Not available when auto_scaling is enabled.

Response

200 Pod restart initiated

Response

200 Array of pods with status

Response

204 Pod deleted

Update pod runtime configuration (auto-healing, persistent storage, autoscaling). Stops the workload, applies changes, and recreates with new settings. Network resources (VIP, DNS, EIP) are preserved.

Request Body (all fields optional)

Edge cases: Enabling auto_scaling forces auto_healing on. Disabling auto_healing also disables auto_scaling. GPU access cannot be changed after creation.

Example — Enable autoscaling

curl -k -X PATCH $API_URL/pods/POD_ID/config \
  -H "X-Auth-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "auto_scaling": true,
    "autoscale_max_replicas": 6,
    "autoscale_cpu_target_millicores": 250
  }'

Example — Enable persistent storage

curl -k -X PATCH $API_URL/pods/POD_ID/config \
  -H "X-Auth-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "persistent": true,
    "persistent_mount_path": "/data"
  }'

Example — Set / rotate env vars

Full replace: fields omitted from the dict are removed from the pod. Pass {} to clear. Triggers a workload recreate so the new values take effect on the running pod.

curl -k -X PATCH $API_URL/pods/POD_ID/config \
  -H "X-Auth-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "env_vars": {
      "ADMIN_EMAILS": "[email protected]",
      "FLASK_SECRET_KEY": "<64-char hex>",
      "LOG_LEVEL": "info"
    }
  }'

Response

200 Updated pod object

409 Pod is stopped or being deleted

Request Body

HTTP Tunnel (Web Apps)

curl -k -X POST $API_URL/pods/POD_ID/tunnel \
  -H "X-Auth-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tunnel_name": "web-app",
    "subdomain": "app",
    "protocol_type": "http",
    "service_port": 80
  }'
# Access: https://app.yourdomain.com

SSH Tunnel (Remote Access)

curl -k -X POST $API_URL/pods/POD_ID/tunnel \
  -H "X-Auth-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tunnel_name": "ssh-access",
    "subdomain": "ssh",
    "protocol_type": "ssh",
    "service_port": 22
  }'
# Connect: cloudflared access ssh --hostname ssh.yourdomain.com

TCP Tunnel (Database)

curl -k -X POST $API_URL/pods/POD_ID/tunnel \
  -H "X-Auth-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tunnel_name": "database",
    "subdomain": "db",
    "protocol_type": "tcp",
    "service_port": 5432
  }'
# Connect: cloudflared access tcp --hostname db.yourdomain.com --url localhost:5432
# Then: psql -h localhost -p 5432 -U myuser mydb

UDP Tunnel (Game Server)

curl -k -X POST $API_URL/pods/POD_ID/tunnel \
  -H "X-Auth-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tunnel_name": "game-server",
    "subdomain": "game",
    "protocol_type": "udp",
    "service_port": 27015
  }'
# Connect directly: game.yourdomain.com:27015

Response

201 Tunnel created

{
  "id": "tunnel-uuid",
  "tunnel_name": "web-tunnel",
  "hostname": "app.yourdomain.com",
  "protocol_type": "http",
  "status": "active"
}

Notes

Uses the pod ID query parameter and auto-derives the tunnel name from the pod.

Response

200 Array of tunnels for the pod

Response

200 Array of tunnels

Response

204 Tunnel deleted

Request Body

Example

curl -k -X POST $API_URL/tenants/YOUR_TENANT_ID/registry-credentials \
  -H "X-Auth-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dockerhub",
    "server": "https://index.docker.io/v1/",
    "username": "myusername",
    "password": "mytoken"
  }'

Response

200 Array of credentials (passwords hidden)

Response

200 Credential deleted

Request Body

Example

curl -k -X POST $API_URL/tenants/TENANT_ID/topology \
  -H "Content-Type: application/json" \
  -d '{
    "token": "YOUR_TOKEN",
    "vpcs": [
      {"name": "production", "enable_internet": true}
    ],
    "subnets": [
      {
        "name": "web",
        "vpc_name": "production",
        "cidr": "10.100.1.0/24",
        "gateway_ip": "10.100.1.1"
      }
    ],
    "pods": [
      {
        "name": "nginx",
        "vpc_name": "production",
        "subnet_name": "web",
        "container_image": "nginx:latest",
        "replica_count": 2,
        "service_port": 80,
        "auto_scaling": true,
        "autoscale_max_replicas": 6,
        "autoscale_cpu_target_millicores": 250
      }
    ]
  }'

Response

200 Current topology as JSON