API examples

Examples

Start the API and PostgreSQL, then call the recommendation endpoint:

Recommendations #

Request

curl -X POST http://localhost:8000/api/recommendations \
  -H "Content-Type: application/json" \
  -d '{"min_vcpu": 2, "min_ram_gb": 4, "arch": "x86_64", "region_constraint": "EU", "max_price_eur_per_hour": 0.2, "limit": 5}'

Response

{
  "recommendations": [
    {
      "instance_type_name": "cx23",
      "provider_slug": "hetzner",
      "region_slug": "fsn1",
      "vcpu": 2,
      "ram_gb": 4.0,
      "score": 0.9898,
      "explain": {
        "resource_fit": 1.0,
        "normalized_price": 0.9797,
        "price_eur_per_hour": 0.0048,
        "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.

↑ Back to menu

TCO example #

When you provide data source and estimated egress, CloudBroker computes total cost (instance + egress + storage + public IP + OS license + cross-AZ) and returns it in explain. Run make ingest-egress first.

Request (with TCO params)

curl -X POST http://localhost:8000/api/recommendations \
  -H "Content-Type: application/json" \
  -d '{
    "min_vcpu": 2,
    "min_ram_gb": 4,
    "arch": "x86_64",
    "region_constraint": "EU",
    "max_price_eur_per_hour": 1.0,
    "limit": 5,
    "data_source_provider": "azure",
    "data_source_region": "westeurope",
    "estimated_egress_gb_per_hour": 1.0
  }'

Response (explain with TCO)

{
  "recommendations": [
    {
      "instance_type_name": "Standard_B2s",
      "provider_slug": "azure",
      "region_slug": "westeurope",
      "vcpu": 2,
      "ram_gb": 4.0,
      "score": 0.95,
      "explain": {
        "resource_fit": 1.0,
        "normalized_price": 0.92,
        "price_eur_per_hour": 0.04,
        "region_is_eu": true,
        "tco_eur_per_hour": 0.06,
        "egress_cost_eur_per_hour": 0.02,
        "storage_cost_eur_per_hour": null,
        "public_ip_cost_eur_per_hour": null,
        "os_license_cost_eur_per_hour": null,
        "cross_az_cost_eur_per_hour": null
      }
    }
  ]
}

Same provider+region as data source yields egress_cost_eur_per_hour: 0. Cross-provider or cross-region adds egress cost.

↑ Back to menu

Other endpoints #

Health check

curl -s http://localhost:8000/health

Response

{
  "status": "ok",
  "checks": {
    "database": {"status": "ok"}
  }
}

Providers

curl -s "http://localhost:8000/api/providers?limit=5"

Response

{
  "items": [
    {"id": 1, "name": "AWS", "slug": "aws", "website": "https://aws.amazon.com", "type": "regional"},
    {"id": 2, "name": "GCP", "slug": "gcp", "website": "https://cloud.google.com", "type": "regional"}
  ],
  "total": 7,
  "limit": 5,
  "offset": 0
}

Regions (by provider)

curl -s "http://localhost:8000/api/regions?provider=aws"

Response

{
  "items": [
    {"id": 1, "provider_id": 1, "name": "EU (Ireland)", "slug": "eu-west-1", "country": "IE", "is_eu": true},
    {"id": 2, "provider_id": 1, "name": "US East (N. Virginia)", "slug": "us-east-1", "country": "US", "is_eu": false}
  ],
  "total": 32,
  "limit": 20,
  "offset": 0
}

Instance types

curl -s "http://localhost:8000/api/instance-types?min_vcpu=2&min_ram_gb=4&arch=x86_64&limit=10"

Response

{
  "items": [
    {"id": 1, "provider_id": 3, "name": "cx23", "family": "cx", "vcpu": 2, "ram_gb": 4.0, "arch": "x86_64"},
    {"id": 2, "provider_id": 1, "name": "t3.medium", "family": "t3", "vcpu": 2, "ram_gb": 4.0, "arch": "x86_64"}
  ],
  "total": 156,
  "limit": 10,
  "offset": 0
}

↑ Back to menu

Interactive docs #

Swagger UI at http://localhost:8000/docs when the API is running. Try requests interactively.

↑ Back to menu