{
  "openapi": "3.1.0",
  "info": {
    "title": "Cleantech Content UK Energy Data API",
    "version": "1.0.0",
    "summary": "UK energy tariffs, the Ofgem price cap and EV public charging prices with provenance on every row.",
    "description": "Verified UK electricity and gas tariff data (unit rates, standing charges, off-peak windows, exit fees, export rates), the Ofgem default tariff cap by region and payment method, and public EV charging prices by network. Every row carries source_url, verified_at, verified_by and confidence. Free tier, then USD 0.01 per call via x402 (USDC on Base) or Stripe Machine Payments, or prepaid credit packs. An MCP server with the same data is at https://mcp.cleantechcontent.co.uk/mcp.",
    "termsOfService": "https://data.cleantechcontent.co.uk/licence/",
    "contact": {
      "name": "Cleantech Content",
      "url": "https://cleantechcontent.co.uk",
      "email": "david@cleantechcontent.co.uk"
    },
    "license": {
      "name": "Cleantech Content data licence",
      "url": "https://data.cleantechcontent.co.uk/licence/"
    }
  },
  "servers": [
    {
      "url": "https://data.cleantechcontent.co.uk"
    }
  ],
  "externalDocs": {
    "url": "https://data.cleantechcontent.co.uk/docs/",
    "description": "Human-readable documentation"
  },
  "tags": [
    {
      "name": "tariffs",
      "description": "Energy tariffs and the Ofgem price cap"
    },
    {
      "name": "charging",
      "description": "Public EV charging networks and prices"
    },
    {
      "name": "meta",
      "description": "Freshness, changelog, sources and enums; never metered"
    },
    {
      "name": "keys and credit",
      "description": "Free keys, credit packs and balances"
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Free or credit API key from POST /v1/keys/free or a credit pack. Optional: 25 calls a day work without any key."
      },
      "x402": {
        "type": "apiKey",
        "in": "header",
        "name": "PAYMENT-SIGNATURE",
        "description": "x402 v2 payment (USDC on Base, exact scheme, USD 0.01). Obtain requirements from a 402 response's PAYMENT-REQUIRED header."
      }
    },
    "schemas": {
      "Supplier": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "website": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "TariffRate": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "region_code": {
            "type": "string",
            "enum": [
              "A",
              "B",
              "C",
              "D",
              "E",
              "F",
              "G",
              "H",
              "J",
              "K",
              "L",
              "M",
              "N",
              "P",
              "GB"
            ]
          },
          "payment_method": {
            "type": "string",
            "enum": [
              "direct_debit",
              "standard_credit",
              "prepayment",
              "varying"
            ]
          },
          "unit_rate_pence": {
            "type": [
              "number",
              "null"
            ]
          },
          "standing_charge_pence_per_day": {
            "type": [
              "number",
              "null"
            ]
          },
          "off_peak_rate_pence": {
            "type": [
              "number",
              "null"
            ]
          },
          "off_peak_windows": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "minItems": 2,
              "maxItems": 2
            },
            "description": "Local-time windows, e.g. [[\"23:30\",\"05:30\"]]"
          },
          "peak_rate_pence": {
            "type": [
              "number",
              "null"
            ]
          },
          "peak_windows": {
            "type": [
              "array",
              "null"
            ]
          },
          "bands": {
            "type": [
              "array",
              "null"
            ],
            "description": "Full band list for tariffs with three or more prices."
          },
          "export_rate_pence": {
            "type": [
              "number",
              "null"
            ]
          },
          "export_bands": {
            "type": [
              "array",
              "null"
            ]
          },
          "dynamic_summary": {
            "type": [
              "object",
              "null"
            ],
            "description": "Rolling averages for Agile and Tracker style tariffs."
          },
          "valid_from": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "valid_to": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "source_url": {
            "type": "string",
            "format": "uri",
            "description": "Page or API the value was read from."
          },
          "verified_at": {
            "type": "string",
            "format": "date",
            "description": "Date the value was checked against the source."
          },
          "verified_by": {
            "type": [
              "string",
              "null"
            ],
            "description": "Person or named automated process that verified it."
          },
          "confidence": {
            "type": "string",
            "enum": [
              "verified",
              "unverified"
            ]
          },
          "notes": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "Tariff": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "product_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "type": {
            "type": "string",
            "enum": [
              "standard_variable",
              "fixed",
              "ev_tou",
              "smart_tou",
              "economy_7",
              "tracker",
              "agile",
              "heat_pump",
              "export",
              "ev_addon",
              "prepayment"
            ]
          },
          "fuel": {
            "type": "string",
            "enum": [
              "electricity",
              "gas",
              "dual"
            ]
          },
          "is_export": {
            "type": "boolean"
          },
          "smart_meter_required": {
            "type": "boolean"
          },
          "ev_required": {
            "type": "boolean"
          },
          "heat_pump_required": {
            "type": "boolean"
          },
          "solar_required": {
            "type": "boolean"
          },
          "battery_required": {
            "type": "boolean"
          },
          "compatible_hardware_required": {
            "type": [
              "string",
              "null"
            ]
          },
          "brand_restricted": {
            "type": "boolean"
          },
          "is_variable": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "is_prepay": {
            "type": "boolean"
          },
          "term_months": {
            "type": [
              "integer",
              "null"
            ]
          },
          "exit_fee_pence": {
            "type": [
              "number",
              "null"
            ]
          },
          "exit_fee_type": {
            "type": [
              "string",
              "null"
            ]
          },
          "available_from": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "available_to": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "is_available": {
            "type": "boolean"
          },
          "product_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "origin": {
            "type": "string"
          },
          "supplier": {
            "$ref": "#/components/schemas/Supplier"
          },
          "rates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TariffRate"
            }
          },
          "source_url": {
            "type": "string",
            "format": "uri",
            "description": "Page or API the value was read from."
          },
          "verified_at": {
            "type": "string",
            "format": "date",
            "description": "Date the value was checked against the source."
          },
          "verified_by": {
            "type": [
              "string",
              "null"
            ],
            "description": "Person or named automated process that verified it."
          },
          "confidence": {
            "type": "string",
            "enum": [
              "verified",
              "unverified"
            ]
          },
          "notes": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "PriceCap": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "period_start": {
            "type": "string",
            "format": "date"
          },
          "period_end": {
            "type": "string",
            "format": "date"
          },
          "region_code": {
            "type": "string"
          },
          "fuel": {
            "type": "string",
            "enum": [
              "electricity",
              "gas"
            ]
          },
          "payment_method": {
            "type": "string",
            "enum": [
              "direct_debit",
              "standard_credit",
              "prepayment"
            ]
          },
          "meter_type": {
            "type": "string",
            "enum": [
              "single_rate",
              "economy_7"
            ]
          },
          "unit_rate_pence": {
            "type": [
              "number",
              "null"
            ]
          },
          "standing_charge_pence_per_day": {
            "type": "number"
          },
          "typical_annual_bill_gbp": {
            "type": [
              "number",
              "null"
            ]
          },
          "source_url": {
            "type": "string",
            "format": "uri",
            "description": "Page or API the value was read from."
          },
          "verified_at": {
            "type": "string",
            "format": "date",
            "description": "Date the value was checked against the source."
          },
          "verified_by": {
            "type": [
              "string",
              "null"
            ],
            "description": "Person or named automated process that verified it."
          },
          "confidence": {
            "type": "string",
            "enum": [
              "verified",
              "unverified"
            ]
          },
          "notes": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "ChargingNetwork": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "operator": {
            "type": [
              "string",
              "null"
            ]
          },
          "website": {
            "type": [
              "string",
              "null"
            ]
          },
          "pricing_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "app_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "coverage": {
            "type": [
              "string",
              "null"
            ]
          },
          "source_url": {
            "type": "string",
            "format": "uri",
            "description": "Page or API the value was read from."
          },
          "verified_at": {
            "type": "string",
            "format": "date",
            "description": "Date the value was checked against the source."
          },
          "verified_by": {
            "type": [
              "string",
              "null"
            ],
            "description": "Person or named automated process that verified it."
          },
          "confidence": {
            "type": "string",
            "enum": [
              "verified",
              "unverified"
            ]
          },
          "notes": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "ChargingPrice": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "power_band": {
            "type": "string",
            "enum": [
              "ac_slow_7kw",
              "ac_fast_22kw",
              "dc_rapid_50kw",
              "dc_ultra_150kw_plus"
            ]
          },
          "power_band_label": {
            "type": "string"
          },
          "min_kw": {
            "type": [
              "number",
              "null"
            ]
          },
          "max_kw": {
            "type": [
              "number",
              "null"
            ]
          },
          "pricing_basis": {
            "type": "string",
            "enum": [
              "contactless_payg",
              "app_payg",
              "member",
              "subscription"
            ]
          },
          "plan_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "price_pence_per_kwh": {
            "type": "number"
          },
          "off_peak_price_pence_per_kwh": {
            "type": [
              "number",
              "null"
            ]
          },
          "off_peak_windows": {
            "type": [
              "array",
              "null"
            ]
          },
          "subscription_fee_pence_per_month": {
            "type": [
              "number",
              "null"
            ]
          },
          "connection_fee_pence": {
            "type": [
              "number",
              "null"
            ]
          },
          "idle_fee_pence_per_minute": {
            "type": [
              "number",
              "null"
            ]
          },
          "idle_fee_grace_minutes": {
            "type": [
              "integer",
              "null"
            ]
          },
          "overstay_fee_pence": {
            "type": [
              "number",
              "null"
            ]
          },
          "pre_auth_gbp": {
            "type": [
              "number",
              "null"
            ]
          },
          "valid_from": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "valid_to": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "network": {
            "type": "object",
            "properties": {
              "slug": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "operator": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "pricing_url": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "source_url": {
            "type": "string",
            "format": "uri",
            "description": "Page or API the value was read from."
          },
          "verified_at": {
            "type": "string",
            "format": "date",
            "description": "Date the value was checked against the source."
          },
          "verified_by": {
            "type": [
              "string",
              "null"
            ],
            "description": "Person or named automated process that verified it."
          },
          "confidence": {
            "type": "string",
            "enum": [
              "verified",
              "unverified"
            ]
          },
          "notes": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "CompareResult": {
        "type": "object",
        "properties": {
          "kwh": {
            "type": "number"
          },
          "power_band": {
            "type": "string"
          },
          "power_band_label": {
            "type": "string"
          },
          "basis": {
            "type": [
              "string",
              "null"
            ]
          },
          "table": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "network": {
                  "type": "object"
                },
                "pricing_basis": {
                  "type": "string"
                },
                "plan_name": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "price_pence_per_kwh": {
                  "type": "number"
                },
                "off_peak_price_pence_per_kwh": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "connection_fee_pence": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "subscription_fee_pence_per_month": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "idle_fee_pence_per_minute": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "session_cost_gbp": {
                  "type": "number"
                },
                "session_cost_off_peak_gbp": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "source_url": {
                  "type": "string",
                  "format": "uri",
                  "description": "Page or API the value was read from."
                },
                "verified_at": {
                  "type": "string",
                  "format": "date",
                  "description": "Date the value was checked against the source."
                },
                "verified_by": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Person or named automated process that verified it."
                },
                "confidence": {
                  "type": "string",
                  "enum": [
                    "verified",
                    "unverified"
                  ]
                },
                "notes": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              }
            }
          }
        }
      },
      "ChangelogEntry": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "changed_at": {
            "type": "string",
            "format": "date-time"
          },
          "table_name": {
            "type": "string"
          },
          "row_id": {
            "type": "integer"
          },
          "action": {
            "type": "string",
            "enum": [
              "insert",
              "update",
              "retire"
            ]
          },
          "field_changes": {
            "type": [
              "object",
              "null"
            ]
          },
          "changed_by": {
            "type": [
              "string",
              "null"
            ]
          },
          "reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "source_url": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "Source": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string"
          },
          "publisher": {
            "type": [
              "string",
              "null"
            ]
          },
          "type": {
            "type": [
              "string",
              "null"
            ]
          },
          "first_seen_at": {
            "type": "string",
            "format": "date-time"
          },
          "last_seen_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Status": {
        "type": "object",
        "properties": {
          "datasets": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "rows": {
                  "type": "integer"
                },
                "latest_verified_at": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date"
                },
                "oldest_verified_at": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date"
                }
              }
            }
          },
          "current_price_cap_period": {
            "type": [
              "object",
              "null"
            ]
          },
          "next_price_cap_period": {
            "type": [
              "object",
              "null"
            ]
          },
          "recent_syncs": {
            "type": "array"
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Enums": {
        "type": "object",
        "properties": {
          "regions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "tariff_types": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "power_bands": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "pricing_bases": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "code",
              "message"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "PaymentRequired": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "const": "payment_required"
              },
              "message": {
                "type": "string"
              },
              "resets_at": {
                "type": "string",
                "format": "date-time"
              },
              "payment_options": {
                "type": "object",
                "description": "free_tier, x402, stripe_machine_payments and api_key_credit_packs with prices and endpoints."
              },
              "x402": {
                "type": "object",
                "description": "Decoded x402 PaymentRequired: resource and accepts[]."
              }
            }
          }
        }
      },
      "FreeKey": {
        "type": "object",
        "properties": {
          "api_key": {
            "type": "string"
          },
          "key_id": {
            "type": "string",
            "format": "uuid"
          },
          "tier": {
            "type": "string"
          },
          "calls_per_day": {
            "type": "integer"
          },
          "usage": {
            "type": "string"
          },
          "note": {
            "type": "string"
          }
        }
      },
      "CheckoutResult": {
        "type": "object",
        "properties": {
          "checkout_url": {
            "type": "string",
            "format": "uri"
          },
          "session_id": {
            "type": "string"
          },
          "api_key": {
            "type": "string",
            "description": "Only when a new key was created."
          },
          "key_id": {
            "type": "string"
          },
          "note": {
            "type": "string"
          },
          "pack": {
            "type": "object",
            "properties": {
              "usd": {
                "type": "number"
              },
              "calls": {
                "type": "integer"
              }
            }
          }
        }
      },
      "PackResult": {
        "type": "object",
        "properties": {
          "api_key": {
            "type": "string"
          },
          "key_id": {
            "type": "string"
          },
          "calls_added": {
            "type": "integer"
          },
          "balance_calls": {
            "type": "integer"
          },
          "amount_usd": {
            "type": "number"
          },
          "usage": {
            "type": "string"
          }
        }
      },
      "Balance": {
        "type": "object",
        "properties": {
          "key_id": {
            "type": "string"
          },
          "tier": {
            "type": "string"
          },
          "balance_calls": {
            "type": [
              "integer",
              "null"
            ]
          }
        }
      }
    }
  },
  "security": [
    {},
    {
      "apiKey": []
    },
    {
      "x402": []
    }
  ],
  "paths": {
    "/v1/tariffs": {
      "get": {
        "tags": [
          "tariffs"
        ],
        "operationId": "listTariffs",
        "summary": "List UK energy tariffs with regional rates",
        "description": "Filter by GSP region, tariff type, supplier slug, fuel and payment method. Rates are nested per region and payment method. Only verified, currently available tariffs are returned unless include_unverified or include_unavailable is set.",
        "x-payment-info": {
          "protocols": [
            "x402",
            "mpp"
          ],
          "amount": "0.01",
          "currency": "USD",
          "freeTier": "25 calls per day per address, 100 with a free key"
        },
        "parameters": [
          {
            "name": "region",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "A",
                "B",
                "C",
                "D",
                "E",
                "F",
                "G",
                "H",
                "J",
                "K",
                "L",
                "M",
                "N",
                "P",
                "GB"
              ]
            },
            "description": "GSP group letter A to P, or GB for a national average."
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "standard_variable",
                "fixed",
                "ev_tou",
                "smart_tou",
                "economy_7",
                "tracker",
                "agile",
                "heat_pump",
                "export",
                "ev_addon",
                "prepayment"
              ]
            },
            "description": "Tariff type."
          },
          {
            "name": "supplier",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "example": "octopus-energy"
            },
            "description": "Supplier slug."
          },
          {
            "name": "fuel",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "electricity",
                "gas",
                "dual"
              ]
            },
            "description": "Fuel."
          },
          {
            "name": "payment_method",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "direct_debit",
                "standard_credit",
                "prepayment"
              ]
            },
            "description": "Payment method."
          },
          {
            "name": "include_unverified",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "Also return rows not verified against a primary source."
          },
          {
            "name": "include_unavailable",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "Also return withdrawn tariffs."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            },
            "description": "Page size."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0
            },
            "description": "Offset."
          }
        ],
        "responses": {
          "200": {
            "description": "Tariffs",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Tariff"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "as_of": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date"
                        },
                        "count": {
                          "type": "integer"
                        },
                        "attribution": {
                          "type": "string"
                        },
                        "licence_url": {
                          "type": "string"
                        },
                        "note": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "as_of",
                        "attribution",
                        "licence_url"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad filter",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unknown or revoked API key."
          },
          "402": {
            "description": "Free tier exhausted and no payment presented. Headers carry x402 requirements (PAYMENT-REQUIRED) and a Stripe Machine Payments challenge (WWW-Authenticate: Payment); the body lists every payment option.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequired"
                }
              }
            },
            "headers": {
              "PAYMENT-REQUIRED": {
                "schema": {
                  "type": "string"
                },
                "description": "Base64 JSON x402 PaymentRequired (v2)."
              },
              "WWW-Authenticate": {
                "schema": {
                  "type": "string"
                },
                "description": "MPP Payment challenge."
              }
            }
          }
        }
      }
    },
    "/v1/tariffs/ev": {
      "get": {
        "tags": [
          "tariffs"
        ],
        "operationId": "listEvTariffs",
        "summary": "EV time-of-use tariffs and EV add-ons",
        "x-payment-info": {
          "protocols": [
            "x402",
            "mpp"
          ],
          "amount": "0.01",
          "currency": "USD",
          "freeTier": "25 calls per day per address, 100 with a free key"
        },
        "parameters": [
          {
            "name": "region",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "A",
                "B",
                "C",
                "D",
                "E",
                "F",
                "G",
                "H",
                "J",
                "K",
                "L",
                "M",
                "N",
                "P",
                "GB"
              ]
            },
            "description": "GSP region."
          },
          {
            "name": "supplier",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Supplier slug."
          },
          {
            "name": "include_unverified",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "Include unverified rows."
          }
        ],
        "responses": {
          "200": {
            "description": "EV tariffs",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Tariff"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "as_of": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date"
                        },
                        "count": {
                          "type": "integer"
                        },
                        "attribution": {
                          "type": "string"
                        },
                        "licence_url": {
                          "type": "string"
                        },
                        "note": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "as_of",
                        "attribution",
                        "licence_url"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unknown or revoked API key."
          },
          "402": {
            "description": "Free tier exhausted and no payment presented. Headers carry x402 requirements (PAYMENT-REQUIRED) and a Stripe Machine Payments challenge (WWW-Authenticate: Payment); the body lists every payment option.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequired"
                }
              }
            },
            "headers": {
              "PAYMENT-REQUIRED": {
                "schema": {
                  "type": "string"
                },
                "description": "Base64 JSON x402 PaymentRequired (v2)."
              },
              "WWW-Authenticate": {
                "schema": {
                  "type": "string"
                },
                "description": "MPP Payment challenge."
              }
            }
          }
        }
      }
    },
    "/v1/tariffs/cap": {
      "get": {
        "tags": [
          "tariffs"
        ],
        "operationId": "getPriceCap",
        "summary": "Ofgem default tariff cap by region, fuel and payment method",
        "description": "By default returns the period in force on the requested date (today). The response note lists every period on file.",
        "x-payment-info": {
          "protocols": [
            "x402",
            "mpp"
          ],
          "amount": "0.01",
          "currency": "USD",
          "freeTier": "25 calls per day per address, 100 with a free key"
        },
        "parameters": [
          {
            "name": "region",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "A",
                "B",
                "C",
                "D",
                "E",
                "F",
                "G",
                "H",
                "J",
                "K",
                "L",
                "M",
                "N",
                "P",
                "GB"
              ]
            },
            "description": "GSP region."
          },
          {
            "name": "payment_method",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "direct_debit",
                "standard_credit",
                "prepayment"
              ]
            },
            "description": "Payment method."
          },
          {
            "name": "fuel",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "electricity",
                "gas"
              ]
            },
            "description": "Fuel."
          },
          {
            "name": "period",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "A date inside the cap period wanted."
          },
          {
            "name": "include_history",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "Return all stored periods."
          }
        ],
        "responses": {
          "200": {
            "description": "Cap rows",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PriceCap"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "as_of": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date"
                        },
                        "count": {
                          "type": "integer"
                        },
                        "attribution": {
                          "type": "string"
                        },
                        "licence_url": {
                          "type": "string"
                        },
                        "note": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "as_of",
                        "attribution",
                        "licence_url"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unknown or revoked API key."
          },
          "402": {
            "description": "Free tier exhausted and no payment presented. Headers carry x402 requirements (PAYMENT-REQUIRED) and a Stripe Machine Payments challenge (WWW-Authenticate: Payment); the body lists every payment option.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequired"
                }
              }
            },
            "headers": {
              "PAYMENT-REQUIRED": {
                "schema": {
                  "type": "string"
                },
                "description": "Base64 JSON x402 PaymentRequired (v2)."
              },
              "WWW-Authenticate": {
                "schema": {
                  "type": "string"
                },
                "description": "MPP Payment challenge."
              }
            }
          }
        }
      }
    },
    "/v1/tariffs/{id}": {
      "get": {
        "tags": [
          "tariffs"
        ],
        "operationId": "getTariff",
        "summary": "One tariff by id or slug",
        "x-payment-info": {
          "protocols": [
            "x402",
            "mpp"
          ],
          "amount": "0.01",
          "currency": "USD",
          "freeTier": "25 calls per day per address, 100 with a free key"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Numeric id or slug, e.g. octopus-go-fix-12m-26-08-19-electricity"
          },
          {
            "name": "region",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "A",
                "B",
                "C",
                "D",
                "E",
                "F",
                "G",
                "H",
                "J",
                "K",
                "L",
                "M",
                "N",
                "P",
                "GB"
              ]
            },
            "description": "Return rates for one region only."
          }
        ],
        "responses": {
          "200": {
            "description": "Tariff",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Tariff"
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "as_of": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date"
                        },
                        "count": {
                          "type": "integer"
                        },
                        "attribution": {
                          "type": "string"
                        },
                        "licence_url": {
                          "type": "string"
                        },
                        "note": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "as_of",
                        "attribution",
                        "licence_url"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unknown or revoked API key."
          },
          "402": {
            "description": "Free tier exhausted and no payment presented. Headers carry x402 requirements (PAYMENT-REQUIRED) and a Stripe Machine Payments challenge (WWW-Authenticate: Payment); the body lists every payment option.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequired"
                }
              }
            },
            "headers": {
              "PAYMENT-REQUIRED": {
                "schema": {
                  "type": "string"
                },
                "description": "Base64 JSON x402 PaymentRequired (v2)."
              },
              "WWW-Authenticate": {
                "schema": {
                  "type": "string"
                },
                "description": "MPP Payment challenge."
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/charging/networks": {
      "get": {
        "tags": [
          "charging"
        ],
        "operationId": "listChargingNetworks",
        "summary": "Public EV charging networks",
        "x-payment-info": {
          "protocols": [
            "x402",
            "mpp"
          ],
          "amount": "0.01",
          "currency": "USD",
          "freeTier": "25 calls per day per address, 100 with a free key"
        },
        "parameters": [
          {
            "name": "include_unverified",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "Include networks without verified prices."
          }
        ],
        "responses": {
          "200": {
            "description": "Networks",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ChargingNetwork"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "as_of": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date"
                        },
                        "count": {
                          "type": "integer"
                        },
                        "attribution": {
                          "type": "string"
                        },
                        "licence_url": {
                          "type": "string"
                        },
                        "note": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "as_of",
                        "attribution",
                        "licence_url"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unknown or revoked API key."
          },
          "402": {
            "description": "Free tier exhausted and no payment presented. Headers carry x402 requirements (PAYMENT-REQUIRED) and a Stripe Machine Payments challenge (WWW-Authenticate: Payment); the body lists every payment option.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequired"
                }
              }
            },
            "headers": {
              "PAYMENT-REQUIRED": {
                "schema": {
                  "type": "string"
                },
                "description": "Base64 JSON x402 PaymentRequired (v2)."
              },
              "WWW-Authenticate": {
                "schema": {
                  "type": "string"
                },
                "description": "MPP Payment challenge."
              }
            }
          }
        }
      }
    },
    "/v1/charging/prices": {
      "get": {
        "tags": [
          "charging"
        ],
        "operationId": "listChargingPrices",
        "summary": "Public charging prices by network, power band and pricing basis",
        "x-payment-info": {
          "protocols": [
            "x402",
            "mpp"
          ],
          "amount": "0.01",
          "currency": "USD",
          "freeTier": "25 calls per day per address, 100 with a free key"
        },
        "parameters": [
          {
            "name": "network",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "example": "instavolt"
            },
            "description": "Network slug."
          },
          {
            "name": "power_band",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "ac_slow_7kw",
                "ac_fast_22kw",
                "dc_rapid_50kw",
                "dc_ultra_150kw_plus"
              ]
            },
            "description": "Power band."
          },
          {
            "name": "basis",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "contactless_payg",
                "app_payg",
                "member",
                "subscription"
              ]
            },
            "description": "Pricing basis."
          },
          {
            "name": "include_unverified",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "Include unverified rows."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            },
            "description": "Page size."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Offset."
          }
        ],
        "responses": {
          "200": {
            "description": "Prices",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ChargingPrice"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "as_of": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date"
                        },
                        "count": {
                          "type": "integer"
                        },
                        "attribution": {
                          "type": "string"
                        },
                        "licence_url": {
                          "type": "string"
                        },
                        "note": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "as_of",
                        "attribution",
                        "licence_url"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unknown or revoked API key."
          },
          "402": {
            "description": "Free tier exhausted and no payment presented. Headers carry x402 requirements (PAYMENT-REQUIRED) and a Stripe Machine Payments challenge (WWW-Authenticate: Payment); the body lists every payment option.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequired"
                }
              }
            },
            "headers": {
              "PAYMENT-REQUIRED": {
                "schema": {
                  "type": "string"
                },
                "description": "Base64 JSON x402 PaymentRequired (v2)."
              },
              "WWW-Authenticate": {
                "schema": {
                  "type": "string"
                },
                "description": "MPP Payment challenge."
              }
            }
          }
        }
      }
    },
    "/v1/charging/compare": {
      "get": {
        "tags": [
          "charging"
        ],
        "operationId": "compareChargingCost",
        "summary": "Cost of one charging session across networks",
        "x-payment-info": {
          "protocols": [
            "x402",
            "mpp"
          ],
          "amount": "0.01",
          "currency": "USD",
          "freeTier": "25 calls per day per address, 100 with a free key"
        },
        "parameters": [
          {
            "name": "kwh",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 500,
              "example": 40
            },
            "description": "Energy to add (required)."
          },
          {
            "name": "power_band",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "ac_slow_7kw",
                "ac_fast_22kw",
                "dc_rapid_50kw",
                "dc_ultra_150kw_plus"
              ]
            },
            "description": "Charger power band (required)."
          },
          {
            "name": "basis",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "contactless_payg",
                "app_payg",
                "member",
                "subscription"
              ]
            },
            "description": "Restrict to one pricing basis."
          },
          {
            "name": "include_unverified",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "Include unverified rows."
          }
        ],
        "responses": {
          "200": {
            "description": "Cost table, cheapest first",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CompareResult"
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "as_of": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date"
                        },
                        "count": {
                          "type": "integer"
                        },
                        "attribution": {
                          "type": "string"
                        },
                        "licence_url": {
                          "type": "string"
                        },
                        "note": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "as_of",
                        "attribution",
                        "licence_url"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Missing kwh or power_band",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unknown or revoked API key."
          },
          "402": {
            "description": "Free tier exhausted and no payment presented. Headers carry x402 requirements (PAYMENT-REQUIRED) and a Stripe Machine Payments challenge (WWW-Authenticate: Payment); the body lists every payment option.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequired"
                }
              }
            },
            "headers": {
              "PAYMENT-REQUIRED": {
                "schema": {
                  "type": "string"
                },
                "description": "Base64 JSON x402 PaymentRequired (v2)."
              },
              "WWW-Authenticate": {
                "schema": {
                  "type": "string"
                },
                "description": "MPP Payment challenge."
              }
            }
          }
        }
      }
    },
    "/v1/meta/status": {
      "get": {
        "tags": [
          "meta"
        ],
        "operationId": "getStatus",
        "summary": "Data freshness per dataset (never metered)",
        "responses": {
          "200": {
            "description": "Status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Status"
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "as_of": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date"
                        },
                        "count": {
                          "type": "integer"
                        },
                        "attribution": {
                          "type": "string"
                        },
                        "licence_url": {
                          "type": "string"
                        },
                        "note": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "as_of",
                        "attribution",
                        "licence_url"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/meta/changelog": {
      "get": {
        "tags": [
          "meta"
        ],
        "operationId": "getChangelog",
        "summary": "Recent data changes (never metered)",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "maximum": 500,
              "default": 100
            },
            "description": "Rows."
          },
          {
            "name": "table",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Restrict to one table, e.g. tariff_rates."
          }
        ],
        "responses": {
          "200": {
            "description": "Changelog",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ChangelogEntry"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "as_of": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date"
                        },
                        "count": {
                          "type": "integer"
                        },
                        "attribution": {
                          "type": "string"
                        },
                        "licence_url": {
                          "type": "string"
                        },
                        "note": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "as_of",
                        "attribution",
                        "licence_url"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/meta/sources": {
      "get": {
        "tags": [
          "meta"
        ],
        "operationId": "getSources",
        "summary": "Every source URL cited (never metered)",
        "responses": {
          "200": {
            "description": "Sources",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Source"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "as_of": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date"
                        },
                        "count": {
                          "type": "integer"
                        },
                        "attribution": {
                          "type": "string"
                        },
                        "licence_url": {
                          "type": "string"
                        },
                        "note": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "as_of",
                        "attribution",
                        "licence_url"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/meta/enums": {
      "get": {
        "tags": [
          "meta"
        ],
        "operationId": "getEnums",
        "summary": "Allowed filter values (never metered)",
        "responses": {
          "200": {
            "description": "Enums",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Enums"
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "as_of": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date"
                        },
                        "count": {
                          "type": "integer"
                        },
                        "attribution": {
                          "type": "string"
                        },
                        "licence_url": {
                          "type": "string"
                        },
                        "note": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "as_of",
                        "attribution",
                        "licence_url"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/keys/free": {
      "post": {
        "tags": [
          "keys and credit"
        ],
        "operationId": "createFreeKey",
        "summary": "Issue a free API key (100 calls a day)",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "label": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Key issued (shown once)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeKey"
                }
              }
            }
          },
          "429": {
            "description": "Too many keys from this address today"
          }
        }
      }
    },
    "/v1/credits/checkout": {
      "post": {
        "tags": [
          "keys and credit"
        ],
        "operationId": "createCheckout",
        "summary": "Buy a developer credit pack by card (Stripe Checkout)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "pack": {
                    "type": "string",
                    "enum": [
                      "1200",
                      "7000"
                    ]
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "api_key": {
                    "type": "string",
                    "description": "Existing credit key to top up."
                  }
                },
                "required": [
                  "pack"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checkout link and key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckoutResult"
                }
              }
            }
          }
        }
      }
    },
    "/v1/credits/buy": {
      "post": {
        "tags": [
          "keys and credit"
        ],
        "operationId": "buyPackMpp",
        "summary": "Buy an agent credit pack with Stripe Machine Payments (Shared Payment Token)",
        "description": "Returns a 402 with a WWW-Authenticate: Payment challenge. Retry with the MPP credential to receive a key holding the pack.",
        "x-payment-info": {
          "protocols": [
            "mpp"
          ],
          "amount": "0.50",
          "currency": "USD",
          "description": "50-call pack; packs of 250 (USD 2) and 750 (USD 5) via ?pack="
        },
        "parameters": [
          {
            "name": "pack",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "50",
                "250",
                "750"
              ],
              "default": "50"
            },
            "description": "Pack size."
          }
        ],
        "responses": {
          "200": {
            "description": "Pack issued",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PackResult"
                }
              }
            }
          },
          "402": {
            "description": "MPP challenge",
            "headers": {
              "WWW-Authenticate": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/v1/credits/balance": {
      "get": {
        "tags": [
          "keys and credit"
        ],
        "operationId": "getBalance",
        "summary": "Remaining calls for a credit key",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Balance",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Balance"
                }
              }
            }
          },
          "401": {
            "description": "Unknown key"
          }
        }
      }
    }
  }
}