{"openapi":"3.1.0","info":{"title":"Conversion Encyclopedia API","version":"1.1.0","description":"Public conversion API backed by the generalized engine used by Conversion Encyclopedia. Family and unit values are canonical IDs; contextual slugs and parameters are validated for the selected family at runtime."},"servers":[{"url":"https://conversionencyclopedia.com"}],"paths":{"/api/v1/convert":{"post":{"operationId":"convertMeasurement","summary":"Convert a measurement","description":"Converts through one of the registered agent-callable families. Use canonical family/from/to IDs and provide only the contextual fields required by that family.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversionRequest"},"examples":{"cookingMolasses":{"value":{"family":"cooking","value":37,"from":"gram","to":"tablespoon_us","material":"molasses"}},"length":{"value":{"family":"length","value":37,"from":"foot","to":"meter"}},"temperature":{"value":{"family":"temperature","value":37,"from":"celsius","to":"fahrenheit"}},"materialDensity":{"value":{"family":"material-density","value":37,"from":"gram","to":"liter","material":"water"}},"solutionConcentration":{"value":{"family":"solution-concentration","value":37,"from":"grams_per_liter","to":"moles_per_liter","solute":"sodium-chloride"}},"batteryRuntime":{"value":{"family":"battery-runtime","value":37,"from":"watt_hour","to":"hour","parameters":{"loadWatts":10}}},"videoFileSize":{"value":{"family":"video-file-size","value":37,"from":"minute","to":"megabyte","parameters":{"profile":"1080p-30fps-5mbps"}}},"fuelEconomy":{"value":{"family":"fuel-economy","value":37,"from":"liters_per_100_km","to":"miles_per_us_gallon"}},"camera":{"value":{"family":"camera-focal-equivalence","value":37,"from":"focal_length_mm","to":"horizontal_angle_of_view_degree","parameters":{"sensorProfile":"aps-c-sony-fuji-23-5mm"}}},"beaufort":{"value":{"family":"beaufort-scale","value":10,"from":"meter_per_second","to":"beaufort"}},"animalAge":{"value":{"family":"animal-age","value":5,"from":"animal_year","to":"human_year","parameters":{"profile":"dog-small-breed"}}},"apparel":{"value":{"family":"shoe-size","value":10,"from":"us","to":"uk","parameters":{"cohort":"men"}}},"screenResolution":{"value":{"family":"screen-resolution","value":37,"from":"nhd-640x360","to":"fhd-1920x1080"}}}}}},"responses":{"200":{"description":"Conversion completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversionSuccess"},"examples":{"cookingMolasses":{"value":{"ok":true,"conversion":{"family":"cooking","value":37,"from":"gram","to":"tablespoon_us","material":{"slug":"molasses","label":"Molasses"},"result":{"raw":1.7514792899408285,"display":"1.75147928994"},"basis":{"gramsPerCup":338,"cupMilliliters":236.588,"tablespoonsPerCup":16,"gramsPerTablespoon":21.125,"sourceNote":"density ~1.43 g/mL × 236.588 mL"},"status":"final","confidence":"medium","canonicalPath":"/cooking/grams-to-tablespoons/molasses/","canonicalUrl":"/cooking/grams-to-tablespoons/molasses/"}}}}}}},"400":{"description":"Malformed or structurally invalid input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversionError"},"examples":{"malformed_json":{"value":{"ok":false,"error":{"code":"MALFORMED_JSON","message":"malformed json."}}},"missing_body":{"value":{"ok":false,"error":{"code":"MISSING_BODY","message":"missing body."}}},"invalid_request":{"value":{"ok":false,"error":{"code":"INVALID_REQUEST","message":"invalid request."}}},"non_finite_value":{"value":{"ok":false,"error":{"code":"NON_FINITE_VALUE","message":"non finite value."}}},"missing_parameter":{"value":{"ok":false,"error":{"code":"MISSING_PARAMETER","message":"missing parameter."}}},"invalid_parameter":{"value":{"ok":false,"error":{"code":"INVALID_PARAMETER","message":"invalid parameter."}}}}}}},"404":{"description":"A canonical contextual ID was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversionError"},"examples":{"unknown_material":{"value":{"ok":false,"error":{"code":"UNKNOWN_MATERIAL","message":"unknown material."}}},"unknown_solute":{"value":{"ok":false,"error":{"code":"UNKNOWN_SOLUTE","message":"unknown solute."}}},"unknown_profile":{"value":{"ok":false,"error":{"code":"UNKNOWN_PROFILE","message":"unknown profile."}}}}}}},"405":{"description":"Only POST is supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversionError"},"examples":{"method_not_allowed":{"value":{"ok":false,"error":{"code":"METHOD_NOT_ALLOWED","message":"method not allowed."}}}}}},"headers":{"Allow":{"description":"Supported method.","schema":{"type":"string","const":"POST"}}}},"413":{"description":"The JSON body exceeds 16 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversionError"},"examples":{"payload_too_large":{"value":{"ok":false,"error":{"code":"PAYLOAD_TOO_LARGE","message":"payload too large."}}}}}}},"415":{"description":"Content-Type must be application/json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversionError"},"examples":{"unsupported_content_type":{"value":{"ok":false,"error":{"code":"UNSUPPORTED_CONTENT_TYPE","message":"unsupported content type."}}}}}}},"422":{"description":"The requested conversion cannot be processed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversionError"},"examples":{"unsupported_family":{"value":{"ok":false,"error":{"code":"UNSUPPORTED_FAMILY","message":"unsupported family."}}},"unknown_unit":{"value":{"ok":false,"error":{"code":"UNKNOWN_UNIT","message":"unknown unit."}}},"unsupported_conversion":{"value":{"ok":false,"error":{"code":"UNSUPPORTED_CONVERSION","message":"unsupported conversion."}}},"incompatible_units":{"value":{"ok":false,"error":{"code":"INCOMPATIBLE_UNITS","message":"incompatible units."}}},"out_of_domain":{"value":{"ok":false,"error":{"code":"OUT_OF_DOMAIN","message":"out of domain."}}},"material_not_final":{"value":{"ok":false,"error":{"code":"MATERIAL_NOT_FINAL","message":"material not final."}}},"missing_conversion_basis":{"value":{"ok":false,"error":{"code":"MISSING_CONVERSION_BASIS","message":"missing conversion basis."}}},"no_exact_discrete_match":{"value":{"ok":false,"error":{"code":"NO_EXACT_DISCRETE_MATCH","message":"no exact discrete match."}}},"no_reverse_conversion":{"value":{"ok":false,"error":{"code":"NO_REVERSE_CONVERSION","message":"no reverse conversion."}}},"ambiguous_unit":{"value":{"ok":false,"error":{"code":"AMBIGUOUS_UNIT","message":"ambiguous unit."}}}}}}}}}}},"components":{"schemas":{"ConversionRequest":{"type":"object","additionalProperties":false,"required":["family","value","from","to"],"properties":{"family":{"type":"string","enum":["cooking","length","weight","volume","area","speed","time","pressure","stress","energy","power","data-rate","flow-rate","density","thermal-conductivity","specific-heat-capacity","surface-tension","diffusion-coefficient","concentration","voltage","current","resistance","capacitance","inductance","radiation-activity","radiation-absorbed-dose","radiation-dose-equivalent","dynamic-viscosity","kinematic-viscosity","angle","acceleration","torque","electric-charge","magnetic-flux-density","mass-flow-rate","illuminance","luminous-flux","ancient-length","ancient-mass","ancient-volume","ancient-area","alcohol-dilution","coffee-brewing-ratio","pace","3d-printing-units","typography-units","data-storage","photometry-imaging","astronomy-distance","astronomy-size","astronomy-mass","marine","battery-charge","screen-resolution","beverage","material-density","temperature","historical-temperature-scales","battery-energy","battery-runtime","solution-concentration","fuel-economy","electromagnetic-wavelength-frequency","screen-size-ppi","image-file-size","audio-file-size","video-file-size","camera-focal-equivalence","beaufort-scale","animal-age","shoe-size","ring-size","hat-size","glove-size","belt-size","bra-size","jeans-size","jacket-size"],"description":"Canonical registered agent-callable family ID."},"value":{"type":"number","description":"Finite numeric input."},"from":{"type":"string","minLength":1,"description":"Canonical source UnitId."},"to":{"type":"string","minLength":1,"description":"Canonical destination UnitId."},"material":{"type":"string","minLength":1,"description":"Canonical material slug where required."},"solute":{"type":"string","minLength":1,"description":"Canonical solute slug where required."},"parameters":{"type":"object","description":"Whitelisted family-dependent parameters: voltage, loadWatts, resolutionProfile, profile, sensorProfile, cohort, or fit.","additionalProperties":{"type":["string","number","boolean"]}}}},"ConversionSuccess":{"type":"object","additionalProperties":false,"required":["ok","conversion"],"properties":{"ok":{"type":"boolean","const":true},"conversion":{"$ref":"#/components/schemas/Conversion"}}},"Conversion":{"type":"object","additionalProperties":false,"required":["family","value","from","to","result","basis","canonicalPath","canonicalUrl"],"properties":{"family":{"type":"string"},"value":{"type":"number"},"from":{"type":"string"},"to":{"type":"string"},"material":{"$ref":"#/components/schemas/CanonicalEntity"},"solute":{"$ref":"#/components/schemas/CanonicalEntity"},"profile":{"$ref":"#/components/schemas/Profile"},"result":{"$ref":"#/components/schemas/ConversionValue"},"context":{"type":"object","additionalProperties":true},"basis":{"type":"object","additionalProperties":true},"rounding":{"type":"object","additionalProperties":true},"status":{"type":"string"},"confidence":{"type":"string"},"canonicalPath":{"type":"string","pattern":"^/.+/$"},"canonicalUrl":{"type":"string","pattern":"^/.+/$"}}},"CanonicalEntity":{"type":"object","required":["slug","label"],"additionalProperties":true,"properties":{"slug":{"type":"string"},"label":{"type":"string"}}},"Profile":{"type":"object","required":["id"],"additionalProperties":false,"properties":{"id":{"type":"string"},"label":{"type":"string"}}},"ConversionValue":{"type":"object","additionalProperties":false,"required":["raw","display"],"properties":{"raw":{"type":"number"},"normalized":{"type":"number"},"display":{"type":"string"}}},"ConversionError":{"type":"object","additionalProperties":false,"required":["ok","error"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_REQUEST","MALFORMED_JSON","METHOD_NOT_ALLOWED","MISSING_BODY","PAYLOAD_TOO_LARGE","UNSUPPORTED_CONTENT_TYPE","UNSUPPORTED_FAMILY","NON_FINITE_VALUE","UNKNOWN_MATERIAL","UNKNOWN_SOLUTE","MATERIAL_NOT_FINAL","MISSING_CONVERSION_BASIS","INCOMPATIBLE_UNITS","UNKNOWN_UNIT","UNKNOWN_PROFILE","MISSING_PARAMETER","INVALID_PARAMETER","OUT_OF_DOMAIN","NO_REVERSE_CONVERSION","AMBIGUOUS_UNIT","UNSUPPORTED_CONVERSION","NO_EXACT_DISCRETE_MATCH"]},"message":{"type":"string"}}}}}}}}