{"openapi":"3.1.0","info":{"title":"HitchMargin API","version":"1.0.0-beta","description":"Free beta endpoints for deterministic bumper-pull towing math, NHTSA-backed vehicle identity, and documented manufacturer rating paths. The API does not provide verified vehicle towing ratings or unreviewed configuration ranges.","contact":{"email":"support@hitchmargin.com"},"license":{"name":"HitchMargin API beta terms","url":"https://hitchmargin.com/terms"}},"servers":[{"url":"https://hitchmargin.com/api/v1"}],"paths":{"/health":{"get":{"summary":"Service status and capability boundaries","operationId":"getHealth","responses":{"200":{"description":"Service status"}}}},"/vehicles/makes":{"get":{"summary":"NHTSA make identities for common tow-vehicle types","operationId":"listVehicleMakes","responses":{"200":{"description":"Manufacturer-reported make identities; no vehicle ratings"}}}},"/vehicles/models":{"get":{"summary":"Exact-make NHTSA models for a model year","operationId":"listVehicleModels","parameters":[{"name":"makeId","in":"query","required":true,"schema":{"type":"integer"}},{"name":"year","in":"query","required":true,"schema":{"type":"integer","minimum":1996}}],"responses":{"200":{"description":"Manufacturer-reported model identities; no vehicle ratings"},"400":{"description":"Invalid parameters"}}}},"/vehicles/decode":{"post":{"summary":"Decode VIN identity through NHTSA vPIC","operationId":"decodeVehicleIdentity","description":"The full VIN is sent in the POST body rather than a URL. HitchMargin returns a masked VIN, identity fields, and a source path when a documented manufacturer VIN tool is available. It does not return or invent verified towing ratings or a model-family range.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["vin"],"properties":{"vin":{"type":"string","minLength":17,"maxLength":17},"modelYear":{"type":"integer","minimum":1996}}}}}},"responses":{"200":{"description":"Masked VIN, manufacturer-reported identity fields, and a provenance-gated rating path; numeric ratings are not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleDecodeResponse"}}}},"400":{"description":"Invalid VIN or model year"},"422":{"description":"VIN could not be identified"},"502":{"description":"NHTSA vPIC unavailable or returned an unexpected response"},"504":{"description":"NHTSA vPIC timeout"}}}},"/calculate":{"post":{"summary":"Run the HitchMargin deterministic towing worksheet","operationId":"calculateTowMargins","description":"Calculates from caller-supplied, unverified values for a conventional bumper-pull trailer. A mathematical result is not a statement that a setup is safe, compatible, approved, or legal.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TowInput"},"examples":{"planningWorksheet":{"value":{"payloadRatingLb":1650,"maxTrailerRatingLb":8000,"loadedTrailerWeightLb":6500,"tongueWeightMode":"percent","tongueWeightPercent":13,"measuredTongueWeightLb":null,"occupantsLb":400,"cargoAndAccessoriesLb":120,"hitchHardwareLb":70,"receiverTrailerRatingLb":10000,"receiverTongueRatingLb":1000,"gcwrLb":15000,"loadedTowVehicleWeightLb":5900,"rearGawrLb":null,"actualRearAxleWeightLb":null}}}}}},"responses":{"200":{"description":"Deterministic margin worksheet result"}}}}},"components":{"schemas":{"VehicleDecodeResponse":{"type":"object","required":["dataClass","ratingStatus","data","ratingPath","limitations","source"],"properties":{"dataClass":{"type":"string","const":"vehicle_identity_only"},"ratingStatus":{"type":"string","const":"not_provided"},"data":{"type":"object","description":"Selected NHTSA identity fields with a masked VIN; fields may be null."},"ratingPath":{"$ref":"#/components/schemas/VehicleRatingPath"},"limitations":{"type":"array","items":{"type":"string"}},"source":{"type":"object","description":"NHTSA vPIC identity-data provenance."}}},"VehicleRatingPath":{"type":"object","required":["status","candidateRange","title","explanation","unresolvedChecks","source"],"properties":{"status":{"type":"string","enum":["manufacturer_vin_tool_available","official_documents_required"]},"candidateRange":{"type":"object","required":["status","minimumLb","maximumLb","reason"],"properties":{"status":{"type":"string","const":"not_available"},"minimumLb":{"type":"null"},"maximumLb":{"type":"null"},"reason":{"type":"string"}}},"title":{"type":"string"},"explanation":{"type":"string"},"unresolvedChecks":{"type":"array","items":{"type":"string"}},"source":{"oneOf":[{"type":"null"},{"type":"object","required":["publisher","name","url","actionUrl","actionLabel","scope","reviewedAt"],"properties":{"publisher":{"type":"string"},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"actionUrl":{"type":"string","format":"uri"},"actionLabel":{"type":"string"},"scope":{"type":"string"},"reviewedAt":{"type":"string","format":"date"}}}]}}},"TowInput":{"type":"object","required":["payloadRatingLb","loadedTrailerWeightLb","tongueWeightMode","occupantsLb","cargoAndAccessoriesLb","hitchHardwareLb"],"properties":{"payloadRatingLb":{"type":["number","null"]},"maxTrailerRatingLb":{"type":["number","null"]},"loadedTrailerWeightLb":{"type":["number","null"]},"tongueWeightMode":{"type":"string","enum":["percent","measured"]},"tongueWeightPercent":{"type":["number","null"]},"measuredTongueWeightLb":{"type":["number","null"]},"occupantsLb":{"type":"number"},"cargoAndAccessoriesLb":{"type":"number"},"hitchHardwareLb":{"type":"number"},"receiverTrailerRatingLb":{"type":["number","null"]},"receiverTongueRatingLb":{"type":["number","null"]},"gcwrLb":{"type":["number","null"]},"loadedTowVehicleWeightLb":{"type":["number","null"]},"rearGawrLb":{"type":["number","null"]},"actualRearAxleWeightLb":{"type":["number","null"]}}}}}}