{ "openapi": "3.0.3", "info": { "title": "Overfuel Public API", "version": "1.0", "description": "The Overfuel Public API — dealer-scoped, key-authenticated, **read-only in v1**.\n\n## Getting a key\n\nDealer admins create keys at **dealers.overfuel.com → Settings → API keys**. The full secret is shown **exactly once** at creation (it is stored hashed and cannot be retrieved again — a lost key is revoked and replaced). Each key carries scopes (analytics / cms / crm / inventory / leads × read or write) and is pinned to the dealer account it was created on. **URLs carry no dealer id — the key is the tenant.**\n\n## Authentication\n\nSend the key on every request:\n\n```\nAuthorization: Bearer ofk__\n```\n\n## Rate limiting\n\n- **60 requests/minute per key**, across all endpoints combined (token bucket — sustained ~1 req/sec; short bursts succeed until the bucket drains).\n- 30 failed authentication attempts/minute per source IP.\n- Over a limit → **HTTP 429** with a `Retry-After` header (seconds to wait).\n\n## Errors\n\n| Status | Meaning |\n|---|---|\n| 401 | Missing, malformed, unknown, revoked, or expired key — deliberately indistinguishable |\n| 403 | Valid key, missing scope — the error names the scope required |\n| 404 | Route not in the public catalog, or vehicle not found |\n| 429 | Rate limited (`Retry-After` header) |\n\n## Roadmap\n\nv1 ships the dealer profile and the inventory group (read). The analytics, cms, crm and leads scopes are reserved; endpoints will be documented here as they ship." }, "servers": [ { "url": "https://api.overfuel.com/public/1.0" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Dealer" }, { "name": "Inventory" } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Your dealer API key, verbatim: `ofk__`" } }, "schemas": { "Error": { "type": "object", "properties": { "results": { "type": "object", "properties": { "status": { "type": "boolean" }, "errors": { "type": "string" } } } } } }, "responses": { "Unauthorized": { "description": "Missing, malformed, unknown, revoked, or expired key — deliberately indistinguishable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "results": { "status": false, "errors": "Invalid API key provided" } } } } }, "Forbidden": { "description": "Valid key, missing scope — the error names the scope required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "results": { "status": false, "errors": "API key is missing the required 'inventory.read' scope" } } } } }, "RateLimited": { "description": "Over the per-key or per-IP limit. `Retry-After` header carries seconds to wait.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the bucket refills" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "results": { "status": false, "errors": "Rate limit exceeded" } } } } } } }, "paths": { "/dealer": { "get": { "tags": [ "Dealer" ], "summary": "Get dealer", "operationId": "getDealer", "description": "The account the key belongs to: profile, contact channels, location, social handles, hours, review rating, related rooftops, and domains. Configuration and credentials are never included.\n\n**Scope:** none — any valid key may read its own account.", "responses": { "200": { "description": "Dealer profile", "content": { "application/json": { "example": { "results": { "id": 101, "name": "Jerry Hunt Supercenter - Lexington", "type": "auto", "hidelocation": 0, "phonemain": "3365373020", "phonesales": null, "phoneservice": null, "phoneparts": null, "phonerentals": null, "phonecollision": null, "emailmain": null, "emailsales": null, "emailservice": null, "emailparts": null, "emailrentals": null, "emailcollision": null, "street1": "418 Piedmont Drive", "street2": null, "city": "Lexington", "state": "NC", "postalcode": "27295", "country": "US", "timezone": "America/New_York", "lat": "35.83536550", "lng": "-80.24254400", "facebook": "https://www.facebook.com/jerryhuntsupercenter/", "twitter": "https://twitter.com/JerryHuntSC", "instagram": "https://www.instagram.com/jerryhuntauto/", "youtube": "https://www.youtube.com/channel/UC-T9yOL1nF6qyB2-UWr3_7A", "pinterest": null, "tiktok": null, "linkedin": "https://www.linkedin.com/company/jerry-hunt-supercenter/", "googleplaceid": "ChIJhZ4rp0eYU4gR-wMadl6yqBM", "reviewrating": "4.8", "reviewcount": 11035, "prefix": "lexington", "domains": [], "related": [], "hours": { "sales": { "monday": "9:00 AM - 8:00 PM", "...": "(7 days per department)" } }, "isopen": { "sales": 1, "service": 1, "parts": 1, "rentals": 0, "collision": 0, "formatted": "Open from 9:00 AM to 8:00 PM", "appointmentonly": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/inventory": { "get": { "tags": [ "Inventory" ], "summary": "Search inventory", "operationId": "searchInventory", "description": "List/search the dealer's live inventory. Rows carry the public vehicle shape — never cost or internal notes.\n\n**Sold mode:** `sold=1` returns recently **sold** vehicles instead — the window is `days` back from today (default 14, clamped 1–90, echoed in `meta.days`) and each row additionally carries `solddate`. Sale economics (sold price, cost) are never included.\n\n**Scope:** `inventory.read`", "parameters": [ { "name": "sold", "in": "query", "schema": { "type": "integer", "enum": [ 1 ] }, "description": "Set to 1 for recently sold vehicles (adds solddate per row)" }, { "name": "days", "in": "query", "schema": { "type": "integer", "default": 14, "minimum": 1, "maximum": 90 }, "description": "Sold mode only: window in days back from today" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 25 }, "description": "Rows per page" }, { "name": "offset", "in": "query", "schema": { "type": "integer" }, "description": "Paging offset" }, { "name": "condition", "in": "query", "schema": { "type": "string", "enum": [ "New", "Used", "Certified" ] } }, { "name": "make", "in": "query", "schema": { "type": "string" } }, { "name": "model", "in": "query", "schema": { "type": "string" } }, { "name": "year[gt]", "in": "query", "schema": { "type": "integer" }, "description": "Model year greater-than" }, { "name": "year[lt]", "in": "query", "schema": { "type": "integer" }, "description": "Model year less-than" }, { "name": "price[gt]", "in": "query", "schema": { "type": "integer" } }, { "name": "price[lt]", "in": "query", "schema": { "type": "integer" } }, { "name": "mileage[lt]", "in": "query", "schema": { "type": "integer" } }, { "name": "body", "in": "query", "schema": { "type": "string" }, "description": "Body style" }, { "name": "sortby", "in": "query", "schema": { "type": "string", "example": "price" } }, { "name": "sortorder", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Result page (examples trimmed to one row)", "content": { "application/json": { "examples": { "active": { "summary": "Live inventory (default)", "value": { "results": [ { "vin": "1GNKRHKD1EJ137289", "featuredphoto": null, "id": 1653129, "dealer_id": 101, "status": "active", "statusoverride": "", "featured": 0, "stocknumber": "28402A", "location": "lot", "inventorydate": "2026-06-05", "originalprice": 100000, "price": 8650, "specialprice": 0, "addonprice": 0, "addonpricelabel": null, "addonpricedescription": null, "pricingdisclaimer": null, "msrp": null, "year": 2014, "make": "Chevrolet", "model": "Traverse", "modelnumber": "CR14526", "trim": "2LT", "series": "2LT", "body": "SUV", "condition": "Pre-owned", "certified": 0, "mileage": 119686, "exteriorcolor": "Atlantis Blue Metallic", "interiorcolor": "Ebony", "exteriorcolorstandard": "Blue", "interiorcolorstandard": "Black", "fuel": "Gasoline", "drivetrainstandard": "FWD", "mpgcity": 17, "mpghwy": 24, "evrange": null, "evbatterycapacity": null, "doors": 4, "seatingcapacity": 7, "towingcapacity": 5200, "photocount": 2, "tags": null, "highlights": [ "Automatic climate control", "Backup camera", "Bluetooth", "Fog lights", "Heated seats", "Premium audio", "Remote engine start", "Satellite radio ready", "Side impact airbags", "Third row seat", "Captain seats" ], "dealer": { "name": "Jerry Hunt Supercenter - Lexington", "city": "Lexington", "state": "NC", "phonemain": "3365373020" }, "title": "2014 Chevrolet Traverse 2LT", "url": "/inventory/2014-chevrolet-traverse-2lt-1GNKRHKD1EJ137289", "hot": 0, "new": 0, "wholesale": 0, "discounts": [ { "title": "Recently discounted", "amount": -91350, "percentage": 0 } ], "incentives": [], "adjustmentlabel": null, "finance": { "fees": [], "vehicle_amount": 8650, "shipping_amount": 0, "tradein_amount": 0, "tradein_remainingbalance": 0, "down_payment": 0, "doctitlefees_amount": 0, "tax_amount": 0, "tax_rate": 0, "tax_rate_formatted": 0, "tax_tradeincredit": null, "loan_amount": 8650, "loan_months": 72, "interest_rate": 0.0599, "interest_rate_formatted": 5.99, "credit_score": 740, "credit_tier": "AA", "total_cost": 10318.65, "total_interest": 1668.65, "monthly_payment": 143.31, "available_terms": [ 36, 48, 60, 63, 72, 75, 84 ], "ais_override": false }, "photos": [], "hasstockphoto": false, "video": { "source": null, "url": null, "autoplay": null, "aspectratio": null }, "lease": null, "specials": null, "advertised": null, "is_rv": false } ], "meta": { "cache": false, "limit": 2, "offset": 0, "sortby": "price", "sortorder": "asc", "total": 659 } } }, "sold": { "summary": "sold=1 — recently sold, rows carry solddate", "value": { "results": [ { "id": 1627188, "dealer_id": 101, "vin": "1FTEW1EP4LK000000", "status": "sold", "year": 2020, "make": "Ford", "model": "F-150", "trim": "XLT", "condition": "Pre-owned", "mileage": 41250, "price": 32900, "exteriorcolorstandard": "White", "body": "Pickup truck", "title": "2020 Ford F-150 XLT", "solddate": "2026-09-14 00:00:00", "…": "same public vehicle shape as /inventory, plus solddate" } ], "meta": { "limit": 5, "offset": 0, "days": 14 } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/inventory/{vin}": { "get": { "tags": [ "Inventory" ], "summary": "Get vehicle", "operationId": "getVehicle", "description": "One vehicle's full public detail: identity, pricing with the composed discount stack, specs, photos, highlights, installed options, and history-report links.\n\n**Scope:** `inventory.read`", "parameters": [ { "name": "vin", "in": "path", "required": true, "schema": { "type": "string" }, "description": "VIN or stock number", "example": "KNADM4A34G6646197" } ], "responses": { "200": { "description": "Vehicle detail", "content": { "application/json": { "example": { "results": { "id": 1409450, "dealer_id": 101, "vin": "KNADM4A34G6646197", "status": "sold", "statusoverride": "", "featured": 0, "stocknumber": "K9854A", "location": "lot", "inventorydate": "2026-03-30", "originalprice": 100000, "price": 5989, "adjustmentlabel": null, "specialprice": 0, "specialpricelabel": null, "addonprice": 0, "addonpricelabel": null, "addonpricedescription": null, "msrp": 6450, "year": 2016, "make": "Kia", "model": "Rio", "modelnumber": "31421", "trim": "LX", "series": "", "body": "Sedan", "style": null, "commercial": 0, "condition": "Pre-owned", "certified": 0, "mileage": 104361, "exteriorcolor": "Urban Blue Pearl Metallic", "exteriorcolorstandard": "Blue", "interiorcolor": "Black", "interiorcolorstandard": "Black", "fuel": "Gasoline", "transmission": "6-Speed Manual", "transmissionstandard": "Manual", "drivetrain": "FWD", "drivetrainstandard": "FWD", "engine": "1.6L I4 DGI 16V", "displacement": 1.6, "cylinders": 4, "blocktype": "I", "powercycle": null, "maxhorsepower": 138, "maxhorsepowerat": 6300, "maxtorque": 123, "maxtorqueat": 4850, "aspiration": "Naturally Aspirated", "mpgcity": 27, "mpghwy": 38, "evrange": null, "evbatterycapacity": null, "evchargerrating": null, "doors": 4, "fueltank": 11, "seatingcapacity": 5, "towingcapacity": null, "dimensions": null, "axle": null, "axleratio": "3.83", "reardoorgate": null, "gvwr": null, "emptyweight": null, "loadcapacity": null, "dimension_width": 67.7, "dimension_length": 172, "dimension_height": 57.3, "bedlength": null, "wheelbase": 101.2, "frontwheel": "15.0 x 5.5", "rearwheel": "15.0 x 5.5", "fronttire": "185/65R15", "reartire": "185/65R15", "carfaxurl": "https://www.carfax.com/vehiclehistory/ar20/8rF5McRIu5CBg_Xbg3mvZlduG4uzGIFAWUxq9D7bCjbnUTUQk2wBOiMmBTGntkX1hUxq2DkGHB1F2GKCJyQxSSkdaIjMJeouWaA", "carfaxicon": "https://partnerstatic.carfax.com/img/valuebadge/1own_great.svg", "carfaxalt": "CARFAX 1-Owner Great Value Badge", "carfaxoneowner": 1, "carfaxsnapshotkey": "GmCVxWsgUTJKcEdWXCP9lIvbGhe5g2yPAnuDAOXtmy9ogArWaTde-w-v3Jqx6hMKRC55P_FEcO3TAdZXSDopb1xlDsyE6KslWas", "autocheck": null, "monroneysticker": null, "photocount": 1, "notes": "Recent Arrival! CARFAX One-Owner. Black Cloth. 2016 Urban Blue Pearl Metallic Kia Rio 4D Sedan LX 1.6L I4 DGI 16V FWD

27/38 City/Highway MPG", "tags": null, "highlights": [], "incentives": [], "metatitle": null, "metadescription": null, "vehicledescription": null, "additionaldetails": null, "pricingdisclaimer": null, "hideestimatedpayments": 0, "schemabody": "sedan", "title": "2016 Kia Rio LX", "url": "/inventory/2016-kia-rio-lx-KNADM4A34G6646197", "hot": 0, "new": 0, "bodyshippingstandard": "Car", "photos": [ { "id": 67356619, "large": "https://static.overfuel.com/photos/101/1409450/8afa3f3e-2da6-4826-8e89-f371993408fe.webp", "thumbnail": "https://static.overfuel.com/photos/101/1409450/8afa3f3e-2da6-4826-8e89-f371993408fe-thumb.webp", "isstock": 0, "sortorder": 1 } ], "floorplan_photo": null, "video": { "source": null, "url": null, "autoplay": null, "aspectratio": null }, "discounts": [ { "title": "Recently discounted", "amount": -94011, "percentage": 0 } ], "onhold": false, "tiles": [], "installedoptions": [], "finance": { "fees": [], "vehicle_amount": 5989, "shipping_amount": 0, "tradein_amount": 0, "tradein_remainingbalance": 0, "down_payment": 0, "doctitlefees_amount": 0, "tax_amount": 0, "tax_rate": 0, "tax_rate_formatted": 0, "tax_tradeincredit": null, "loan_amount": 5989, "loan_months": 72, "interest_rate": 0.0599, "interest_rate_formatted": 5.99, "credit_score": 740, "credit_tier": "AA", "total_cost": 7144.33, "total_interest": 1155.33, "monthly_payment": 99.23, "available_terms": [ 36, 48, 60, 63, 72, 75, 84 ], "ais_override": false }, "lease": null, "specials": null, "advertised": null, "is_rv": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Vehicle not found for this dealer", "content": { "application/json": { "example": { "error": "Vehicle not found" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/filters": { "get": { "tags": [ "Inventory" ], "summary": "Get search facets", "operationId": "getFilters", "description": "The facet values available for searching this dealer's live inventory — makes, models, years, price bounds, body styles, colors, features. Facets appear only when the dealer's inventory populates them.\n\n**Scope:** `inventory.read`", "responses": { "200": { "description": "Facets (example trimmed)", "content": { "application/json": { "example": { "results": { "filters": { "price": { "min": 8650, "max": 100000, "buckets": { "8000": 7, "12000": 10, "16000": 56, "20000": 100, "24000": 132, "28000": 121, "32000": 63, "36000": 60, "40000": 38, "44000": 22, "48000": 18, "52000": 10, "56000": 4, "60000": 3, "64000": 3, "68000": 3, "72000": 2, "76000": 1, "80000": 1, "84000": 0, "88000": 0, "92000": 0, "96000": 1, "100000": 4 } }, "make": { "counts": { "Acura": 9, "Alfa Romeo": 1, "Audi": 11, "BMW": 12, "Buick": 3, "Cadillac": 7, "Chevrolet": 56, "Chrysler": 7, "Dodge": 23, "Ford": 51, "GMC": 16, "Honda": 47, "Hyundai": 52, "INFINITI": 7, "Jeep": 47, "Kia": 42, "Lexus": 14, "Lincoln": 3, "Mazda": 30, "Mercedes-Benz": 14, "Mitsubishi": 8, "Nissan": 73, "Porsche": 1, "Ram": 24, "Subaru": 19, "Tesla": 4, "Toyota": 50, "Volkswagen": 21, "Volvo": 7 } }, "condition": { "counts": { "Pre-owned": 659 } }, "year": { "min": 2014, "max": 2026 }, "…": "27 facets total: price, make, model, trim, condition, dealer_id, location, year, mileage, body, seatingcapacity, highlights, exteriorcolorstandard, interiorcolorstandard, fuel, transmissionstandard, drivetrainstandard, engine, gvwr, rv_type, numslideouts, length_buckets, manufacturer, modelgroups, trimgroups, mpghwy, mpgcity" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } } }