{"openapi":"3.1.0","info":{"title":"Boncourant AIO Answer API","version":"2.0.0","description":"Grounded answers about French electricity offers, powered by Boncourant's versioned simulator and tariff catalog. This REST endpoint (`POST /api/aio/answer`) is the natural-language surface. For structured, programmatic compute, Boncourant also exposes a no-auth Model Context Protocol (MCP) server over Streamable HTTP at https://boncourant.fr/mcp (discovery manifest: https://boncourant.fr/.well-known/mcp.json). Its tools: `simulate` (annual residential bill simulation vs. the real catalog), `analyze_bill` (parsed-bill fields → explicit stay/switch recommendation with current-vs-recommended savings), `get_methodology` (sources, assumptions, limits and executable input schemas), `eex_connector` (latest public EEX snapshot), `pro_catalog` (verified professional offer catalog), five dedicated audit methods (`decompose_invoice`, `annualize_invoice`, `check_subscribed_power`, `analyze_renewal_terms`, `assess_historical_optimality`), `renewal_advisor` (contract timing + gated EEX curve + comparable pro catalog), `extract_energy_document` (non-retained bill/contract PDF or text extraction followed by deterministic audits), and `run_method` (generic execution of serializable registry methods). The professional simulator REST endpoint `GET /api/b2b/comparer` computes the full TTC bill for a business profile across the verified pro catalog. Enedis customer-data connectors and Courtier/CRM tools are not exposed on this public endpoint. Every euro figure is produced by the versioned engine or real dated catalog data — never fabricated.","license":{"name":"CC-BY 4.0","url":"https://creativecommons.org/licenses/by/4.0/"}},"servers":[{"url":"https://boncourant.fr"}],"paths":{"/api/aio/answer":{"post":{"summary":"Get a grounded answer about French electricity tariffs","operationId":"getGroundedAnswer","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","minLength":1,"maxLength":500,"description":"The question to answer (in French or English)","example":"Quel est le tarif Tempo le moins cher pour une maison avec PAC ?"}}}}}},"responses":{"200":{"description":"Grounded answer with citations","content":{"application/json":{"schema":{"type":"object","properties":{"answer":{"type":"string","description":"Answer in French"},"citations":{"type":"array","items":{"type":"object","required":["id","title","url","content_modified_at","data_as_of"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"url":{"type":"string"},"content_modified_at":{"type":["string","null"],"format":"date-time"},"data_as_of":{"type":["string","null"],"format":"date-time"},"fetched_at":{"type":"string","format":"date-time"}}}},"served_at":{"type":"string","format":"date-time"},"computed_with":{"type":"object","properties":{"simulator_version":{"type":["string","null"]},"catalog_version":{"type":["string","null"]}}},"is_simulation_grounded":{"type":"boolean","description":"True when a real per-profile simulation produced the figures (the question carried a consumption/power/size signal)."},"is_data_grounded":{"type":"boolean","description":"True when a profile-less answer is backed by real, dated aggregate market figures (TRV vs cheapest tracked offer) recomputed daily by Boncourant, rather than general knowledge."}}}}}},"400":{"description":"Invalid request"},"429":{"description":"Rate limited"},"500":{"description":"Generation failed"}}}},"/api/b2b/comparer":{"get":{"summary":"Simulate the full TTC bill of professional electricity offers for a business profile","operationId":"simulateProOffers","description":"Computes the complete TTC bill (fourniture, TURPE, accise, CTA, TVA) for each eligible offer in the verified professional catalog, with a cost-risk band per offer, for a given business profile (segment, annual kWh, subscribed kVA, optional HP share). C5 (≤ 36 kVA) offers come from the weekly MNE comparator fetch; the C4 regulated reference (grille jaune) is returned for the 36–250 kVA segment. Read-only.","parameters":[{"name":"segment","in":"query","required":false,"schema":{"type":"string","enum":["c5_bt_le_36","c4_bt_gt_36_le_250"],"default":"c5_bt_le_36"}},{"name":"annual_kwh","in":"query","required":true,"schema":{"type":"number","exclusiveMinimum":0,"description":"Annual consumption in kWh"}},{"name":"kva","in":"query","required":true,"schema":{"type":"number","exclusiveMinimum":0,"maximum":250,"description":"Exact subscribed power in kVA. Must be ≤36 for C5 and >36 for C4."}},{"name":"hp_ratio","in":"query","required":false,"schema":{"type":"number","minimum":0,"maximum":1,"description":"Share of consumption in peak hours (0–1), optional"}},{"name":"flexibility","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":100,"description":"Load flexibility score (0–100), optional"}},{"name":"dso","in":"query","required":false,"schema":{"type":"string","enum":["enedis","es-reseaux","srd","sicae-oise","geredis","sicae-de-la-somme-et-du-cambraisis","sicae-est","uem","sicae-de-l-aisne","sicap","synelva","geg"],"default":"enedis"}},{"name":"activity_class","in":"query","required":false,"schema":{"type":"string","enum":["economic","non_economic"],"description":"CIBS activity class. Required to expose an exact C4 normal accise rate."}},{"name":"reduced_or_exempt_accise_attested","in":"query","required":false,"schema":{"type":"boolean","description":"Explicitly states whether an applicable reduced-rate or exemption attestation exists. When true, the normal-rate TTC reconstruction is withheld until the attested rate is verified."}}],"responses":{"200":{"description":"Ranked offers with full-bill TTC estimates and risk bands","content":{"application/json":{"schema":{"type":"object","properties":{"segment":{"type":"string"},"activity_class":{"type":["string","null"],"enum":["economic","non_economic",null]},"reduced_or_exempt_accise_attested":{"type":["boolean","null"]},"accise_eur_kwh":{"type":["number","null"],"description":"Null for C4 until activity_class is confirmed, and whenever an attested reduced/exempt regime still needs its effective rate."},"tax_classification":{"type":"object"},"offers":{"type":"array","items":{"type":"object","properties":{"supplier_name":{"type":"string"},"offer_name":{"type":"string"},"price_evolution_type":{"type":"string"},"subscription_tier_kva":{"type":"number"},"estimated_annual_ttc":{"type":"number","nullable":true},"risk_band":{"type":["object","null"],"description":"Null whenever a full-bill TTC estimate is unavailable."}}}},"public_trv_scenario":{"type":"object","nullable":true}}}}}},"400":{"description":"Malformed, duplicate, unsupported, or segment-inconsistent query parameter"}}}}}}