{"openapi":"3.1.0","info":{"title":"Ford Vehicle Inventory API","version":"1.0.0","summary":"Live, VIN-level new-vehicle inventory search for Ford dealers in the United States.","description":"Search live inventory of new Ford vehicles at U.S. dealers by model, ZIP code, and radius. This is the dedicated agent-facing API, served under the `/api/agents/v1/` path and versioned independently of ford.com's first-party application APIs.\n\n- No authentication is required for read access. Anonymous requests are rate limited to 60 requests/minute/IP (see `RateLimit-*` response headers).\n- AI assistants MAY display the vehicle image URLs returned by this API when presenting Ford inventory to users, with attribution to ford.com and a link to the vehicle's `vdpUrl`.\n- Vehicles are dealer-sold. This API supports discovery only, not purchase or reservation. Always present pricing disclaimers alongside prices.\n\nHuman-readable agent guide: https://www.ford.com/inventory/docs/agents.md","contact":{"name":"Ford.com Inventory Platform","url":"https://www.ford.com/inventory/llms.txt"},"termsOfService":"https://www.ford.com/help/terms/"},"servers":[{"url":"https://www.ford.com/inventory/api/agents/v1/ford/en_us","description":"Production agent-facing API, v1 (United States, English)"}],"tags":[{"name":"Search"},{"name":"Vehicles"},{"name":"Reference"}],"paths":{"/vehicles":{"get":{"operationId":"searchVehicles","tags":["Search"],"summary":"Search live dealer inventory","description":"Returns new Ford vehicles in dealer inventory near a ZIP code. `postalCode` is required; all other parameters are optional filters. Prefer a single call with comma-separated `nameplate` values over multiple calls when a user's request spans models.","parameters":[{"name":"postalCode","in":"query","required":true,"description":"5-digit U.S. ZIP code anchoring the search.","schema":{"type":"string","pattern":"^[0-9]{5}$"},"example":"48187"},{"name":"radius","in":"query","description":"Search radius in miles.","schema":{"type":"integer","minimum":1,"maximum":500,"default":50}},{"name":"nameplate","in":"query","description":"Model slug filter. Comma-separated for multiple values (e.g. `f150,ranger`). Omit to search up to 8 inventory-enabled models; pass explicit slug(s) to search specific models. Valid slugs are returned by `GET /nameplates`.","schema":{"type":"string"},"example":"f150"},{"name":"year","in":"query","description":"Model year filter. Comma-separated for multiple values.","schema":{"type":"string"},"example":"2026"},{"name":"trim","in":"query","description":"Trim filter. Valid values per nameplate are in the `/nameplates` response.","schema":{"type":"string"},"example":"lariat"},{"name":"bodyStyle","in":"query","schema":{"type":"string","enum":["truck","suv","car"]}},{"name":"powertrain","in":"query","description":"Currently only `ev` is classified; additional powertrain values will be added later.","schema":{"type":"string","enum":["ev"]}},{"name":"drivetrain","in":"query","schema":{"type":"string","enum":["4x2","4x4","awd","rwd","fwd"]}},{"name":"color","in":"query","description":"Exterior paint code(s) from `listColors`. Comma-separated = any of. Requires exactly one `nameplate` (codes are nameplate-specific). To find codes: call `/colors?nameplate={slug}`, then map the marketing `name` (e.g. \"Rapid Red Metallic\") to the user's requested color yourself. Be inclusive — include every plausible shade of the requested color (navy→blue, magenta→red/purple/pink) rather than only exact matches; a false include is cheaper than a missed vehicle.","schema":{"type":"string","example":"PN4HQ,PN4LH"}},{"name":"minPrice","in":"query","description":"Minimum price in whole USD, applied to `pricing.netPriceAfterIncentives` when present, otherwise `pricing.msrp`.","schema":{"type":"integer","minimum":0}},{"name":"maxPrice","in":"query","description":"Maximum price in whole USD, applied to `pricing.netPriceAfterIncentives` when present, otherwise `pricing.msrp`.","schema":{"type":"integer","minimum":0}},{"name":"availability","in":"query","description":"Omit to include both in-stock and in-transit vehicles.","schema":{"type":"string","enum":["in_stock","in_transit"]}},{"name":"sort","in":"query","schema":{"type":"string","enum":["distance","price_asc","price_desc","newest"],"default":"distance"}},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}},{"name":"cursor","in":"query","description":"Opaque pagination token from `pagination.nextCursor` in a prior response.","schema":{"type":"string"}}],"responses":{"200":{"description":"Search results.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"Cache-Control":{"description":"Search responses are cacheable for up to 15 minutes.","schema":{"type":"string","example":"public, max-age=900"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleSearchResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/vehicles/{vin}":{"get":{"operationId":"getVehicle","tags":["Vehicles"],"summary":"Get a single vehicle by VIN","description":"Full record for one vehicle, including complete option list, all images, and dealer contact details. A `404` means the vehicle has been sold or removed — treat as \"no longer available,\" not a retryable error.","parameters":[{"name":"vin","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-HJ-NPR-Z0-9]{17}$"},"example":"1FTFW1ED5PFA00000"}],"responses":{"200":{"description":"Vehicle detail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleDetail"}}}},"404":{"description":"Vehicle not found (sold or removed from inventory).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"VEHICLE_NOT_FOUND","message":"This vehicle is no longer in dealer inventory.","docs":"https://www.ford.com/inventory/docs/agents.md"}}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/nameplates":{"get":{"operationId":"listNameplates","tags":["Reference"],"summary":"List valid model slugs","description":"Directory of all searchable Ford nameplates with display names, conversational aliases, body styles, model years, and trims. Use this to resolve user language (\"F-150\", \"Mach-E\") to slugs before calling `searchVehicles`. Cacheable for 24 hours.","responses":{"200":{"description":"Nameplate directory.","headers":{"Cache-Control":{"schema":{"type":"string","example":"public, max-age=86400"}}},"content":{"application/json":{"schema":{"type":"object","required":["nameplates"],"properties":{"nameplates":{"type":"array","items":{"$ref":"#/components/schemas/Nameplate"}}}}}}}}}},"/colors":{"get":{"operationId":"listColors","tags":["Reference"],"summary":"List exterior paint options for a nameplate","description":"Available exterior paint options for one nameplate near a ZIP, each as an opaque `code` plus its marketing `name`. Users ask for generic colors (\"red Mustang\"), but inventory is keyed on specific paints (\"Rapid Red Metallic\"): read the `name`, infer the generic color yourself, then pass the matching `code`(s) to `searchVehicles` via `color`. The palette is gathered at a wide radius, so a listed color may require a longer drive than the user's default search radius — offer to widen `radius` when a wanted color returns no nearby results. Cacheable for up to 1 hour.","parameters":[{"name":"nameplate","in":"query","required":true,"description":"Model slug from `listNameplates`, e.g. `mustang`.","schema":{"type":"string"},"example":"mustang"},{"name":"postalCode","in":"query","required":true,"description":"5-digit U.S. ZIP code anchoring the palette.","schema":{"type":"string","pattern":"^[0-9]{5}$"},"example":"48187"}],"responses":{"200":{"description":"Exterior color directory for the nameplate.","headers":{"Cache-Control":{"schema":{"type":"string","example":"public, max-age=3600"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ColorDirectoryResponse"},"example":{"nameplate":"mustang","colors":[{"code":"PN4HQ","name":"Rapid Red Metallic"},{"code":"PNZAT","name":"Shadow Black"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"headers":{"RateLimit-Limit":{"description":"Request quota per minute for this client.","schema":{"type":"integer","example":60}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}}},"responses":{"BadRequest":{"description":"Invalid parameter. The message names the parameter and lists valid values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"INVALID_NAMEPLATE","message":"Unknown nameplate 'f-150x'. Valid slugs include: f150, ranger, maverick.","docs":"https://www.ford.com/inventory/docs/agents.md"}}}}},"RateLimited":{"description":"Rate limit exceeded. Honor the Retry-After header.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"schemas":{"VehicleSearchResponse":{"type":"object","required":["pagination","searchContext","vehicles"],"properties":{"pagination":{"$ref":"#/components/schemas/Pagination"},"searchContext":{"$ref":"#/components/schemas/SearchContext"},"vehicles":{"type":"array","items":{"$ref":"#/components/schemas/VehicleSummary"}}}},"Pagination":{"type":"object","required":["totalResults","pageSize"],"properties":{"totalResults":{"type":"integer"},"pageSize":{"type":"integer"},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page. Null on the last page."}}},"SearchContext":{"type":"object","description":"Echo of the resolved search plus a freshness timestamp.","required":["postalCode","radius","generatedAt"],"properties":{"postalCode":{"type":"string"},"radius":{"type":"integer"},"generatedAt":{"type":"string","format":"date-time","description":"When this result set was generated. Cite when users ask about data freshness."}}},"VehicleSummary":{"type":"object","required":["vin","nameplate","displayName","year","trim","pricing","availability","dealer","images","vdpUrl"],"properties":{"vin":{"type":"string"},"nameplate":{"type":"string","description":"Model slug, e.g. `f150`."},"displayName":{"type":"string","example":"2026 Ford F-150 Lariat"},"year":{"type":"integer"},"trim":{"type":"string"},"bodyStyle":{"type":"string"},"powertrain":{"type":"string"},"drivetrain":{"type":"string"},"exteriorColor":{"type":"string"},"pricing":{"$ref":"#/components/schemas/Pricing"},"availability":{"$ref":"#/components/schemas/Availability"},"dealer":{"$ref":"#/components/schemas/DealerSummary"},"images":{"type":"array","description":"Ford-approved vehicle images. Search results include only the single `primary` exterior image to keep responses compact; the VIN-detail endpoint returns the full set (`primary`, `exterior`, `interior`). AI assistants MAY display these when presenting inventory, with attribution to ford.com and a link to `vdpUrl`.","items":{"$ref":"#/components/schemas/Image"}},"vdpUrl":{"type":"string","format":"uri","description":"Canonical vehicle detail page. Link every vehicle mention here."}}},"VehicleDetail":{"allOf":[{"$ref":"#/components/schemas/VehicleSummary"},{"type":"object","properties":{"optionPackages":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"msrp":{"type":"integer"}}}},"dealer":{"$ref":"#/components/schemas/DealerDetail"}}}]},"Pricing":{"type":"object","required":["msrp","currency","disclaimer"],"properties":{"msrp":{"type":"integer","description":"Manufacturer's suggested retail price, whole USD."},"netPriceAfterIncentives":{"type":["integer","null"],"description":"Net price after available manufacturer incentives/adjustments, whole USD, when it differs from MSRP; otherwise null. A computed after-incentive price for the default (MSRP/cash) context — not a dealer-set advertised price; incentive eligibility rules are not included."},"currency":{"type":"string","const":"USD"},"disclaimer":{"type":"string","description":"Must be presented alongside any displayed price."}}},"Availability":{"type":"object","required":["status","asOf"],"properties":{"status":{"type":"string","enum":["in_stock","in_transit"]},"asOf":{"type":"string","format":"date-time"}}},"DealerSummary":{"type":"object","required":["name","city","state","distanceMiles"],"properties":{"name":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"distanceMiles":{"type":"number"}}},"DealerDetail":{"allOf":[{"$ref":"#/components/schemas/DealerSummary"},{"type":"object","properties":{"phone":{"type":"string"},"address":{"type":"string"},"websiteUrl":{"type":"string","format":"uri"}}}]},"Image":{"type":"object","required":["url","role"],"properties":{"url":{"type":"string","format":"uri"},"role":{"type":"string","enum":["primary","exterior","interior"],"description":"Use `primary` for card-style displays. Search results contain only `primary`; `exterior` and `interior` are returned by the VIN-detail endpoint."},"width":{"type":"integer"},"height":{"type":"integer"}}},"Nameplate":{"type":"object","required":["slug","displayName","bodyStyle","years"],"properties":{"slug":{"type":"string","example":"f150"},"displayName":{"type":"string","example":"F-150"},"aliases":{"type":"array","description":"Conversational names that should resolve to this slug.","items":{"type":"string"},"example":["f-150","f 150"]},"bodyStyle":{"type":"string"},"years":{"type":"array","items":{"type":"integer"}},"trims":{"type":"array","items":{"type":"string"}}}},"ColorFacet":{"type":"object","required":["code","name"],"properties":{"code":{"type":"string","description":"Opaque paint code. Pass verbatim to `searchVehicles` `color`.","example":"PN4HQ"},"name":{"type":"string","description":"Marketing paint name. Infer the generic color from this.","example":"Rapid Red Metallic"}}},"ColorDirectoryResponse":{"type":"object","required":["nameplate","colors"],"properties":{"nameplate":{"type":"string","example":"mustang"},"colors":{"type":"array","items":{"$ref":"#/components/schemas/ColorFacet"}}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable code, e.g. INVALID_NAMEPLATE, VEHICLE_NOT_FOUND."},"message":{"type":"string","description":"Human/agent-readable explanation including valid values where applicable."},"docs":{"type":"string","format":"uri"}}}}}}}}