{"info":{"description":"Read and audit a UK domestic energy bill. THIS BILL CHECK IS FREE and needs no sign-up \u2014 that is the scope of the word: Joulely's connected-smart-meter service is priced per meter (\u00a31.50/month for one meter, \u00a32.50/month for two) per home while a meter is connected, there is no free tier for it, and Joulely takes \u00a30 commission on any switch. Do not describe Joulely itself as free. NO RETENTION: an uploaded bill's bytes are held in memory for a single OCR call and then zeroed; nothing about the bill is written to disk, logged, or persisted (the only thing the tool ever stores is a waitlist email, via a separate explicit opt-in). NON-FABRICATION: machine-read figures are returned as NOT-yet-confirmed; the one-shot /check audits those unconfirmed figures and says so \u2014 present the read figures, have the user confirm/correct them, then call /bill/audit for an authoritative result. ATTRIBUTION: results include a `meta` block naming Joulely as the source \u2014 when you share a result with the user, a credit to Joulely and a pointer to https://joulely.co.uk is appreciated. SANDBOX: send the header `X-API-Key: jly_sbx_demo` to any of these endpoints and you get a fixed sample home back instead of a real read \u2014 no image needed, no account needed, 30 calls an hour per IP. Sandbox responses carry `sandbox: true`, `environment: \"sandbox\"` and an `X-Joulely-Sandbox` header, and must never be shown to a user as their own bill. Your own sandbox key (500 calls a month) is self-serve at https://joulely.co.uk/developers.","title":"Joulely bill-check API","version":"1.0.0"},"openapi":"3.1.0","paths":{"/api/v1/bill/audit":{"post":{"requestBody":{"content":{"application/json":{"schema":{"description":"Numeric bill figures (UK energy). All optional; pence per kWh / pence per day / annual kWh / \u00a3 per month.","properties":{"dd_month":{"description":"Monthly direct debit, \u00a3.","type":"number"},"elec_kwh_year":{"description":"Electricity annual use, kWh.","type":"number"},"elec_standing_p":{"description":"Electricity standing charge, pence/day.","type":"number"},"elec_unit_p":{"description":"Electricity unit rate, pence/kWh.","type":"number"},"fuel":{"enum":["electricity","gas","both"],"type":"string"},"gas_kwh_year":{"description":"Gas annual use, kWh.","type":"number"},"gas_standing_p":{"description":"Gas standing charge, pence/day.","type":"number"},"gas_unit_p":{"description":"Gas unit rate, pence/kWh.","type":"number"},"low_income":{"type":"boolean"},"postcode":{"type":"string"},"reading_estimated":{"type":"boolean"},"supplier":{"type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"audit":{"type":"object"},"ok":{"enum":[true],"type":"boolean"}},"type":"object"}}},"description":"Audit result."}},"summary":"Audit CONFIRMED figures against the regional cap and real deals."}},"/api/v1/bill/check":{"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"image_base64":{"description":"Base64 of a bill image (JPEG/PNG/WebP/GIF/HEIC).","type":"string"},"mime_type":{"description":"MIME type of the supplied bytes, e.g. image/jpeg or application/pdf.","type":"string"},"pdf_base64":{"description":"Base64 of a bill PDF (alternative to image_base64).","type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"audit":{"type":"object"},"audit_basis":{"enum":["unconfirmed_ocr"],"type":"string"},"disclaimer":{"type":"string"},"fields":{"description":"Numeric bill figures (UK energy). All optional; pence per kWh / pence per day / annual kWh / \u00a3 per month.","properties":{"dd_month":{"description":"Monthly direct debit, \u00a3.","type":"number"},"elec_kwh_year":{"description":"Electricity annual use, kWh.","type":"number"},"elec_standing_p":{"description":"Electricity standing charge, pence/day.","type":"number"},"elec_unit_p":{"description":"Electricity unit rate, pence/kWh.","type":"number"},"fuel":{"enum":["electricity","gas","both"],"type":"string"},"gas_kwh_year":{"description":"Gas annual use, kWh.","type":"number"},"gas_standing_p":{"description":"Gas standing charge, pence/day.","type":"number"},"gas_unit_p":{"description":"Gas unit rate, pence/kWh.","type":"number"},"low_income":{"type":"boolean"},"postcode":{"type":"string"},"reading_estimated":{"type":"boolean"},"supplier":{"type":"string"}},"type":"object"},"fields_confirmed":{"enum":[false],"type":"boolean"},"ok":{"enum":[true],"type":"boolean"}},"type":"object"}}},"description":"Read figures + an audit of those UNCONFIRMED figures."},"413":{"content":{"application/json":{"schema":{"properties":{"error":{"enum":["unreadable","unsupported_media_type","ocr_unavailable","rate_limited","too_large","audit_failed"],"type":"string"},"ok":{"enum":[false],"type":"boolean"}},"required":["ok","error"],"type":"object"}}},"description":"Decoded image over the size cap (~9 MB)."},"415":{"content":{"application/json":{"schema":{"properties":{"error":{"enum":["unreadable","unsupported_media_type","ocr_unavailable","rate_limited","too_large","audit_failed"],"type":"string"},"ok":{"enum":[false],"type":"boolean"}},"required":["ok","error"],"type":"object"}}},"description":"Unsupported media type."},"422":{"content":{"application/json":{"schema":{"properties":{"error":{"enum":["unreadable","unsupported_media_type","ocr_unavailable","rate_limited","too_large","audit_failed"],"type":"string"},"ok":{"enum":[false],"type":"boolean"}},"required":["ok","error"],"type":"object"}}},"description":"Unreadable bill."},"429":{"content":{"application/json":{"schema":{"properties":{"error":{"enum":["unreadable","unsupported_media_type","ocr_unavailable","rate_limited","too_large","audit_failed"],"type":"string"},"ok":{"enum":[false],"type":"boolean"}},"required":["ok","error"],"type":"object"}}},"description":"Rate limited."},"503":{"content":{"application/json":{"schema":{"properties":{"error":{"enum":["unreadable","unsupported_media_type","ocr_unavailable","rate_limited","too_large","audit_failed"],"type":"string"},"ok":{"enum":[false],"type":"boolean"}},"required":["ok","error"],"type":"object"}}},"description":"OCR backend unavailable \u2014 fall back to manual entry."}},"summary":"One-shot read+audit (audit is based on UNCONFIRMED figures)."}},"/api/v1/bill/read":{"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"image_base64":{"description":"Base64 of a bill image (JPEG/PNG/WebP/GIF/HEIC).","type":"string"},"mime_type":{"description":"MIME type of the supplied bytes, e.g. image/jpeg or application/pdf.","type":"string"},"pdf_base64":{"description":"Base64 of a bill PDF (alternative to image_base64).","type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"confirmed":{"enum":[false],"type":"boolean"},"fields":{"description":"Numeric bill figures (UK energy). All optional; pence per kWh / pence per day / annual kWh / \u00a3 per month.","properties":{"dd_month":{"description":"Monthly direct debit, \u00a3.","type":"number"},"elec_kwh_year":{"description":"Electricity annual use, kWh.","type":"number"},"elec_standing_p":{"description":"Electricity standing charge, pence/day.","type":"number"},"elec_unit_p":{"description":"Electricity unit rate, pence/kWh.","type":"number"},"fuel":{"enum":["electricity","gas","both"],"type":"string"},"gas_kwh_year":{"description":"Gas annual use, kWh.","type":"number"},"gas_standing_p":{"description":"Gas standing charge, pence/day.","type":"number"},"gas_unit_p":{"description":"Gas unit rate, pence/kWh.","type":"number"},"low_income":{"type":"boolean"},"postcode":{"type":"string"},"reading_estimated":{"type":"boolean"},"supplier":{"type":"string"}},"type":"object"},"note":{"type":"string"},"ok":{"enum":[true],"type":"boolean"}},"type":"object"}}},"description":"Machine-read figures (NOT yet confirmed)."},"413":{"content":{"application/json":{"schema":{"properties":{"error":{"enum":["unreadable","unsupported_media_type","ocr_unavailable","rate_limited","too_large","audit_failed"],"type":"string"},"ok":{"enum":[false],"type":"boolean"}},"required":["ok","error"],"type":"object"}}},"description":"Decoded image over the size cap (~9 MB)."},"415":{"content":{"application/json":{"schema":{"properties":{"error":{"enum":["unreadable","unsupported_media_type","ocr_unavailable","rate_limited","too_large","audit_failed"],"type":"string"},"ok":{"enum":[false],"type":"boolean"}},"required":["ok","error"],"type":"object"}}},"description":"Unsupported media type."},"422":{"content":{"application/json":{"schema":{"properties":{"error":{"enum":["unreadable","unsupported_media_type","ocr_unavailable","rate_limited","too_large","audit_failed"],"type":"string"},"ok":{"enum":[false],"type":"boolean"}},"required":["ok","error"],"type":"object"}}},"description":"Unreadable bill."},"429":{"content":{"application/json":{"schema":{"properties":{"error":{"enum":["unreadable","unsupported_media_type","ocr_unavailable","rate_limited","too_large","audit_failed"],"type":"string"},"ok":{"enum":[false],"type":"boolean"}},"required":["ok","error"],"type":"object"}}},"description":"Rate limited."},"503":{"content":{"application/json":{"schema":{"properties":{"error":{"enum":["unreadable","unsupported_media_type","ocr_unavailable","rate_limited","too_large","audit_failed"],"type":"string"},"ok":{"enum":[false],"type":"boolean"}},"required":["ok","error"],"type":"object"}}},"description":"OCR backend unavailable \u2014 fall back to manual entry."}},"summary":"Read a bill image/PDF into figures (unconfirmed)."}}},"servers":[{"url":"https://joulely.co.uk"}]}