API endpoint

POST /api/recommendations — ranked VM recommendations across 7 clouds. One request, cost-ranked results.

Endpoints overview

See working curl examples → Examples

Flow

Send constraints (vCPU, RAM, arch, region, max price). CloudBroker filters, scores, and returns a cost-ranked list. Used by Cloudburst Autoscaler for cost-aware Kubernetes burst; any script or controller can call it.

flowchart LR
    Client["Client / Cloudburst"]
    Client -->|"POST /api/recommendations"| CloudBroker
    CloudBroker -->|"ranked recommendations"| Client
            

Endpoint

POST /api/recommendations — Send a JSON body with min_vcpu, min_ram_gb, arch, region_constraint, max_price_eur_per_hour, allowed_providers, and other constraints. CloudBroker returns ranked recommendations.

Request (example)

curl -X POST http://localhost:8000/api/recommendations \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "min_vcpu": 2,
    "min_ram_gb": 4,
    "arch": "x86_64",
    "region_constraint": "EU",
    "max_price_eur_per_hour": 0.2,
    "allowed_providers": ["gcp", "hetzner", "scaleway"],
    "limit": 5
  }'

Response (example)

{
  "recommendations": [
    {
      "instance_type_name": "cx23",
      "provider_slug": "hetzner",
      "region_slug": "fsn1",
      "vcpu": 2,
      "ram_gb": 4.0,
      "price_eur_per_hour": 0.0048,
      "score": 0.9898,
      "explain": {
        "resource_fit": 1.0,
        "normalized_price": 0.9797,
        "region_is_eu": true,
        "tco_eur_per_hour": null,
        "egress_cost_eur_per_hour": null
      }
    }
  ]
}

arch is required. When TCO params are provided, tco_eur_per_hour, egress_cost_eur_per_hour, and other cost components are populated in explain. How scoring works → Article 3

Authentication

All routes under /api (except /health and /api/metrics) require X-API-Key. Auth is bypassed in development when API_KEY is unset.

Other endpoints

GET /api/providers, /api/regions, /api/instance-types, /api/prices, /api/price-analytics/changes, /api/price-analytics/trends. See API Surface and Examples.

← Back to home