{"openapi":"3.1.0","info":{"title":"Karboncheck API","description":"Carbon intelligence API built on ADEME Base Carbone and Agribalyse data.","version":"1.0.0"},"paths":{"/mcp.json":{"get":{"summary":"Get Mcp Manifest","description":"Expose a lightweight MCP preparation manifest.","operationId":"get_mcp_manifest_mcp_json_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/ping":{"get":{"summary":"Ping","operationId":"ping_ping_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"head":{"summary":"Ping Head","operationId":"ping_head_ping_head","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/register":{"post":{"summary":"Register User","operationId":"register_user_api_register_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/my-usage":{"get":{"summary":"My Usage","operationId":"my_usage_api_my_usage_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}}}}},"/api/recherche":{"get":{"summary":"Recherche Api","operationId":"recherche_api_api_recherche_get","parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","title":"Query"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/estimate":{"post":{"summary":"Estimate Api","operationId":"estimate_api_api_estimate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EstimateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EstimateResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/compare-materials":{"post":{"summary":"Compare Materials Api","operationId":"compare_materials_api_api_compare_materials_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompareMaterialsRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompareMaterialsResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AgentSearchPayload":{"properties":{"query":{"type":"string","title":"Query"},"source_requested":{"type":"string","title":"Source Requested","default":"auto"},"source_used":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Used"},"ambiguous":{"type":"boolean","title":"Ambiguous","default":false},"best_match":{"anyOf":[{"$ref":"#/components/schemas/SearchResult"},{"type":"null"}]},"warnings":{"items":{"$ref":"#/components/schemas/WarningMessage"},"type":"array","title":"Warnings"},"alternatives":{"items":{"$ref":"#/components/schemas/AlternativeMatch"},"type":"array","title":"Alternatives"}},"type":"object","required":["query"],"title":"AgentSearchPayload","description":"Agent-ready search block nested in the historical search response."},"AlternativeMatch":{"properties":{"factor_name":{"type":"string","title":"Factor Name"},"factor_value":{"type":"number","title":"Factor Value"},"factor_unit":{"type":"string","title":"Factor Unit"},"match_confidence":{"type":"number","title":"Match Confidence"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"},"data_origin":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Origin"}},"type":"object","required":["factor_name","factor_value","factor_unit","match_confidence"],"title":"AlternativeMatch","description":"Compact alternative factor proposal for agent-oriented responses."},"CompareMaterialsRequest":{"properties":{"options":{"items":{"type":"string"},"type":"array","title":"Options"},"quantity":{"type":"number","title":"Quantity"},"unit":{"type":"string","title":"Unit"},"source":{"type":"string","title":"Source","default":"auto"}},"type":"object","required":["options","quantity","unit"],"title":"CompareMaterialsRequest","description":"Structured comparison input for materials-oriented decisions."},"CompareMaterialsResult":{"properties":{"quantity":{"type":"number","title":"Quantity"},"unit":{"type":"string","title":"Unit"},"source_requested":{"type":"string","title":"Source Requested","default":"auto"},"options":{"items":{"$ref":"#/components/schemas/ComparedMaterialOption"},"type":"array","title":"Options"},"ranking":{"items":{"type":"string"},"type":"array","title":"Ranking"},"best_low_carbon_option":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Best Low Carbon Option"},"warnings":{"items":{"$ref":"#/components/schemas/WarningMessage"},"type":"array","title":"Warnings"}},"type":"object","required":["quantity","unit"],"title":"CompareMaterialsResult","description":"Normalized decision-oriented comparison result for materials."},"ComparedMaterialOption":{"properties":{"material":{"type":"string","title":"Material"},"status":{"type":"string","title":"Status","default":"ok"},"matched_query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Matched Query"},"match_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Match Confidence"},"factor_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Factor Name"},"factor_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Factor Value"},"factor_unit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Factor Unit"},"result_kgco2e":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Result Kgco2E"},"result_unit":{"type":"string","title":"Result Unit","default":"kgCO2e"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"},"method":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Method"},"data_origin":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Origin"},"warnings":{"items":{"$ref":"#/components/schemas/WarningMessage"},"type":"array","title":"Warnings"}},"type":"object","required":["material"],"title":"ComparedMaterialOption","description":"Single option returned by the material comparison endpoint/tool."},"EmissionCO2e":{"properties":{"valeur":{"type":"number","title":"Valeur"},"unite":{"type":"string","title":"Unite"},"incertitude":{"$ref":"#/components/schemas/IncertitudeInterval"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"},"date_de_modification":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date De Modification"}},"type":"object","required":["valeur","unite","incertitude"],"title":"EmissionCO2e","description":"Represents a CO2e emission value together with its metadata."},"EstimateRequest":{"properties":{"query":{"type":"string","title":"Query"},"quantity":{"type":"number","title":"Quantity"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unit"},"source":{"type":"string","title":"Source","default":"auto"}},"type":"object","required":["query","quantity"],"title":"EstimateRequest","description":"Structured estimate input for HTTP and agent tools."},"EstimateResult":{"properties":{"query":{"type":"string","title":"Query"},"quantity":{"type":"number","title":"Quantity"},"quantity_unit":{"type":"string","title":"Quantity Unit"},"matched_query":{"type":"string","title":"Matched Query"},"match_confidence":{"type":"number","title":"Match Confidence"},"factor_name":{"type":"string","title":"Factor Name"},"factor_value":{"type":"number","title":"Factor Value"},"factor_unit":{"type":"string","title":"Factor Unit"},"result_kgco2e":{"type":"number","title":"Result Kgco2E"},"result_unit":{"type":"string","title":"Result Unit","default":"kgCO2e"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"},"method":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Method"},"data_origin":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Origin"},"warnings":{"items":{"$ref":"#/components/schemas/WarningMessage"},"type":"array","title":"Warnings"},"alternatives":{"items":{"$ref":"#/components/schemas/AlternativeMatch"},"type":"array","title":"Alternatives"}},"type":"object","required":["query","quantity","quantity_unit","matched_query","match_confidence","factor_name","factor_value","factor_unit","result_kgco2e"],"title":"EstimateResult","description":"Normalized estimate result for agent-facing HTTP and tool responses."},"GroupedResult":{"properties":{"regroupement":{"type":"string","title":"Regroupement"},"meilleur_resultat":{"$ref":"#/components/schemas/SearchResultItem"},"variantes":{"items":{"$ref":"#/components/schemas/SearchResultItem"},"type":"array","title":"Variantes"}},"type":"object","required":["regroupement","meilleur_resultat"],"title":"GroupedResult","description":"Aggregates result variants sharing the same regroupement key."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"IncertitudeInterval":{"properties":{"min":{"type":"number","title":"Min"},"max":{"type":"number","title":"Max"}},"type":"object","required":["min","max"],"title":"IncertitudeInterval","description":"Numeric range describing the uncertainty around a CO2e value."},"RegisterRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email"}},"type":"object","required":["email"],"title":"RegisterRequest","description":"Payload for user registration."},"RegisterResponse":{"properties":{"api_key":{"type":"string","title":"Api Key"}},"type":"object","required":["api_key"],"title":"RegisterResponse","description":"Response containing the freshly generated API key."},"SearchResponse":{"properties":{"ambigue":{"type":"boolean","title":"Ambigue","default":false},"suggestions":{"items":{"type":"string"},"type":"array","title":"Suggestions"},"meilleure recommandation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Meilleure Recommandation"},"moteur utilisé":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Moteur Utilisé"},"base de recherche":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Base De Recherche"},"resultats":{"anyOf":[{"items":{"$ref":"#/components/schemas/SearchResultItem"},"type":"array"},{"type":"null"}],"title":"Resultats"},"regroupements":{"items":{"$ref":"#/components/schemas/GroupedResult"},"type":"array","title":"Regroupements"},"agent":{"anyOf":[{"$ref":"#/components/schemas/AgentSearchPayload"},{"type":"null"}]}},"type":"object","title":"SearchResponse","description":"Canonical JSON structure returned by the `/api/recherche` endpoint."},"SearchResult":{"properties":{"matched_query":{"type":"string","title":"Matched Query"},"match_confidence":{"type":"number","title":"Match Confidence"},"factor_name":{"type":"string","title":"Factor Name"},"factor_value":{"type":"number","title":"Factor Value"},"factor_unit":{"type":"string","title":"Factor Unit"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"},"method":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Method"},"data_origin":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Origin"},"warnings":{"items":{"$ref":"#/components/schemas/WarningMessage"},"type":"array","title":"Warnings"},"alternatives":{"items":{"$ref":"#/components/schemas/AlternativeMatch"},"type":"array","title":"Alternatives"}},"type":"object","required":["matched_query","match_confidence","factor_name","factor_value","factor_unit"],"title":"SearchResult","description":"Normalized best-match structure exposed to agents."},"SearchResultItem":{"properties":{"nom":{"type":"string","title":"Nom"},"affichage_nom":{"type":"string","title":"Affichage Nom"},"categorie":{"type":"string","title":"Categorie"},"groupe":{"type":"string","title":"Groupe"},"regroupement":{"type":"string","title":"Regroupement"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"},"emission":{"$ref":"#/components/schemas/EmissionCO2e"},"localisation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Localisation"},"commentaire":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Commentaire"},"source":{"type":"string","title":"Source"},"pertinence_score":{"type":"number","title":"Pertinence Score"},"valeur":{"type":"number","title":"Valeur","readOnly":true},"unite":{"type":"string","title":"Unite","readOnly":true},"incertitude":{"$ref":"#/components/schemas/IncertitudeInterval","readOnly":true}},"type":"object","required":["nom","affichage_nom","categorie","groupe","regroupement","emission","source","pertinence_score","valeur","unite","incertitude"],"title":"SearchResultItem","description":"Single search hit enriched with business metadata and scoring."},"UsageResponse":{"properties":{"calls_used":{"type":"integer","title":"Calls Used"},"quota":{"type":"integer","title":"Quota"},"calls_remaining":{"type":"integer","title":"Calls Remaining"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["calls_used","quota","calls_remaining","created_at"],"title":"UsageResponse","description":"API usage metadata returned to authenticated clients."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WarningMessage":{"properties":{"code":{"type":"string","title":"Code"},"message":{"type":"string","title":"Message"},"severity":{"type":"string","title":"Severity","default":"warning"}},"type":"object","required":["code","message"],"title":"WarningMessage","description":"Structured warning exposed to agents and API clients."}}}}