GET /api/v1/energy/carbon/{project_id}

{
  "project_id": "proj_climate_q1",
  "energy_kwh": 0.0042,
  "carbon_kg_co2e": 0.0018,
  "carbon_intensity_gco2_per_kwh": 428,
  "renewable_pct": 62
}

POST /api/v1/energy/budget

{
  "project_id": "proj_climate_q1",
  "monthly_kwh_limit": 100,
  "monthly_co2_kg_limit": 50,
  "on_exceed": "warn",
  "notify_webhook": "https://myorg.com/webhooks/energy-alert"
}

GET /api/v1/energy/budget/{project_id}

{
  "project_id": "proj_climate_q1",
  "period": "2025-01",
  "used_kwh": 34.2,
  "limit_kwh": 100,
  "used_co2_kg": 14.6,
  "limit_co2_kg": 50,
  "pct_kwh_used": 34.2,
  "pct_co2_used": 29.2,
  "status": "within_budget"
}

POST /api/v1/energy/schedule

{
  "job_payload": {
    "circuit": "OPENQASM 2.0; ...",
    "shots": 2048,
    "backend": "azure_quantum_ionq_aria"
  },
  "deadline": "2025-01-16T08:00:00Z",
  "carbon_target_gco2_per_kwh": 200,
  "prefer_renewable": true
}

{
  "scheduled_job_id": "sched_xyz",
  "estimated_start": "2025-01-15T22:30:00Z",
  "forecast_carbon_gco2_per_kwh": 185,
  "forecast_renewable_pct": 78,
  "savings_vs_now_pct": 24
}

GET /api/v1/energy/carbon/{project_id}

curl -H "Authorization: Bearer $QCOS_API_KEY" \
  "https://api.softquantus.com/api/v1/energy/carbon/proj_q1" \
  -o carbon_report_jan2025.json

import os
import time
import requests

API_KEY = os.environ["QCOS_API_KEY"]
BASE_URL = "https://api.softquantus.com"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# Check current carbon intensity before submitting
budget = requests.get(
    f"{BASE_URL}/api/v1/energy/budget/proj_climate_q1",
    headers=HEADERS
).json()
print(f"CO₂ budget used: {budget['pct_co2_used']:.1f}%")

if budget["status"] == "blocked":
    print("Energy budget exceeded — deferring to next billing period")
else:
    # Schedule for a green window within the next 12 hours
    resp = requests.post(
        f"{BASE_URL}/api/v1/energy/schedule",
        headers=HEADERS,
        json={
            "job_payload": {
                "circuit": 'OPENQASM 2.0; include "qelib1.inc"; qreg q[2]; creg c[2]; h q[0]; cx q[0],q[1]; measure q -> c;',
                "shots": 1024,
                "backend": "statevector_sim"
            },
            "deadline": "2025-01-15T22:00:00Z",
            "carbon_target_gco2_per_kwh": 250,
            "prefer_renewable": True
        }
    )
    resp.raise_for_status()
    sched = resp.json()
    print(f"Job scheduled: {sched['scheduled_job_id']}")
    print(f"Estimated start: {sched['estimated_start']}")
    print(f"Forecast carbon intensity: {sched['forecast_carbon_gco2_per_kwh']} gCO₂/kWh")
    print(f"Carbon savings vs. now: {sched['savings_vs_now_pct']}%")