{"openapi":"3.1.0","info":{"title":"Ford API (Bowmark)","version":"e833508f87ff","description":"Ford US new-vehicle shopping: live VIN-level dealer inventory near a ZIP, one vehicle by VIN, the model/trim directory and its paint palette, the build-and-price configurator, model specs and MSRP, current incentives, the dealer locator, and recall lookup by VIN. Five functions are callable now. The dealer locator returns Ford dealers near a US ZIP with full address, phone, coordinates, per-day sales and service hours, Ford's own capability flags (EV-certified, commercial fleet, pickup-and-delivery) and links to the dealer's own site and inventory. The nameplate directory returns every Ford model inventory can be searched by — slug, display name, aliases, body style, model years and trims — and resolves a person's own words (\"F-150\", \"mach e\", \"Super Duty\") to the slug the other inventory endpoints take. `getOffers` returns Ford's live, ZIP-regional incentives for a model — cash back, APR financing (with every term Ford offers, not just the headline one) and any lease programs, each with its own dates, disclaimer and eligibility category, broken out per trim. `getVehicle` reads one specific vehicle by VIN — full trim, pricing with Ford's required disclaimer, availability, the holding dealer's contact details, the FULL image set (exterior AND interior, not just the one card image a search result carries) and every option package — and returns `null` rather than throwing when Ford reports the vehicle sold or removed, which its own docs call a real, non-retryable answer. `getRecalls` returns the open safety recalls and Customer Satisfaction Programs Ford has published against a VIN — campaign number, issue date, description, safety risk and remedy for each — splitting regulator-mandated recalls from Ford's own goodwill FSAs, with `null` for a well-formed VIN Ford has no record of and an empty result (no recalls, no FSAs) for a known VIN with no open actions. The other four declared functions are still stubs.\n\nEvery function Bowmark has for Ford (ford.com) as one HTTP call. Each runs on Bowmark's infrastructure with the same billing, rules and response envelope as `POST /v1/run`. The whole API: https://api.bowmark.ai/openapi.json. Guide: https://bowmark.ai/docs/api.","contact":{"email":"support@bowmark.ai","url":"https://bowmark.ai/docs/api"}},"servers":[{"url":"https://api.bowmark.ai"}],"security":[{"bearer":[]},{"apiKeyHeader":[]}],"paths":{"/v1/sites/ford/findDealers":{"post":{"operationId":"findDealers","summary":"Ford dealers near a US ZIP, nearest first, each with its street address, phone, coordinates, per-day sales and service hours, Ford's own capability flags (\"EV Certified Dealers\", \"Pickup and Delivery\"","description":"Ford dealers near a US ZIP, nearest first, each with its street address, phone, coordinates, per-day sales and service hours, Ford's own capability flags (\"EV Certified Dealers\", \"Pickup and Delivery\", \"National fleet Pricing\"), Ford-certified status, its P&A code and links to its own site, hours, service scheduler and new/used inventory. `near` is a US ZIP (\"48126\" or \"48126-3227\") — Ford's dealer endpoint takes a postal code only and refuses a city or address, because Ford's own page geocodes those in the browser before calling it. `radiusMiles` defaults to 50 (max 300), `limit` to 10 (max 100, Ford's own ceiling). Results are strictly inside the radius: a search with no dealer in range returns an empty list rather than the far-away dealer Ford's own site pads with. Returns only franchised Ford dealers, never the independent collision and glass shops Ford's combined locator mixes in.\n\nCalls `bowmark.providers.ford.findDealers`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<fordDealerSearch>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"arg0":{}},"required":["arg0"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/ford/listNameplates":{"post":{"operationId":"listNameplates","summary":"Every Ford model the US inventory surface can be searched by — its slug (the identifier the other inventory endpoints take), Ford's display name, Ford's own conversational aliases, body style, model y","description":"Every Ford model the US inventory surface can be searched by — its slug (the identifier the other inventory endpoints take), Ford's display name, Ford's own conversational aliases, body style, model years and trims. Call it with no arguments for the whole directory (22 nameplates as measured), or pass `match` with whatever a person actually said — \"F-150\", \"mach e\", \"Super Duty\" — to get the rows that answer to it. Matching is exact on a normalized form: case-folded with ®/™, spaces, hyphens and dots removed, which is what makes a user's \"F-150\" reach a row whose aliases Ford publishes as \"f-150®\", \"f150®\" and \"f 150®\". It is not fuzzy, so \"Bronco\" returns Bronco and not Bronco Sport. A name can legitimately name two models — \"Super Duty\" is both `superduty` and `superduty-commercial`, \"Transit\" is both `transit-van-wagon` and `transitcommercial` — so the result is a list, and an empty one means Ford has no such model rather than that the lookup failed.\n\nCalls `bowmark.providers.ford.listNameplates`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<fordNameplateDirectory>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"arg0":{}},"required":["arg0"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/ford/getOffers":{"post":{"operationId":"getOffers","summary":"Ford's current incentives for one model near a US ZIP — cash back, APR financing (every term Ford offers on a program, e.g.","description":"Ford's current incentives for one model near a US ZIP — cash back, APR financing (every term Ford offers on a program, e.g. 36/48/60/72/84-month options, not just the headline rate) and any lease programs — broken out per trim, each with its start/end date, Ford's own disclaimer text, its machine program code, and a `category` (\"Retail\" public vs. \"Private\" military/loyalty/first-responder) so a caller can tell a program anyone qualifies for from one that needs proof this function cannot itself check. `nameplate` is the slug `listNameplates` returns (\"f150\", \"bronco-sport\"); a handful of commercial-chassis nameplates the inventory API lists have no incentives page at all and are refused by name, measured rather than guessed. `postalCode` is required — incentives are regional, and the SAME model/year at two ZIPs 2,000 miles apart returns genuinely different programs. `year` defaults to the newest model year Ford is currently running incentives on for that nameplate.\n\nCalls `bowmark.providers.ford.getOffers`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<fordOffers>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"type":"object","properties":{"nameplate":{"type":"string"},"postalCode":{"type":"string"},"year":{"type":"number"}},"required":["nameplate","postalCode"],"additionalProperties":true,"description":"TypeScript: `{ nameplate: string; postalCode: string; year?: number }`"}},"required":["args"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/ford/getVehicle":{"post":{"operationId":"getVehicle","summary":"Reads one specific vehicle by its 17-character VIN — full trim, exterior color, complete pricing with Ford's required disclaimer, live availability, the holding dealer's name/address/phone/website, th","description":"Reads one specific vehicle by its 17-character VIN — full trim, exterior color, complete pricing with Ford's required disclaimer, live availability, the holding dealer's name/address/phone/website, the FULL image set (`primary`, `exterior` AND `interior` — a `searchInventory` result carries `primary` only), every option package, and the canonical `vdpUrl` Ford's own docs say to link on any mention. `vin` is a required argument, matching Ford's own pattern (17 characters, excluding I/O/Q) and checked locally before spending a request. Returns `null` — not an error — when Ford answers `VEHICLE_NOT_FOUND`: Ford's own docs call a 404 here \"sold or removed... not a retryable error\", so a vehicle that sold between search and read is a real, unsurprising answer rather than a failure.\n\nCalls `bowmark.providers.ford.getVehicle`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<fordVehicle | null>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vin":{"type":"string","description":"TypeScript: `string`"}},"required":["vin"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/ford/getRecalls":{"post":{"operationId":"getRecalls","summary":"Reads the open safety recalls and Customer Satisfaction Programs (FSAs) Ford has published against one specific VIN, and what each one says to do — the same answer an owner or a used-car buyer gets on","description":"Reads the open safety recalls and Customer Satisfaction Programs (FSAs) Ford has published against one specific VIN, and what each one says to do — the same answer an owner or a used-car buyer gets on Ford's owner-support recalls page. `vin` is required and locally validated against the same 17-character pattern `getVehicle` uses (A-H, J-N, P, R-Z, 0-9). Returns `null` — not an error — when the VIN is well-formed but unknown to Ford (the page sets `isVinInvalid: true`); the call surfaces `noRecalls: true` for a known VIN with no open actions, and the response separates regulator-mandated `recalls` from optional `customerSatisfactionPrograms` (the latter are Ford's free goodwill fixes, NOT safety recalls). Each record carries Ford's own campaign number, issue date, the free-form description, the stated safety risk, the prescribed remedy, and the status Ford reports. When Ford's recall upstream fails, the call returns a successful shape with `apiError: true` and the upstream's own error message in `warnings` — a transient 5xx shouldn't kill the caller. No sign-in: the page is public.\n\nCalls `bowmark.providers.ford.getRecalls`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<fordVehicleRecalls | null>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vin":{"type":"string","description":"TypeScript: `string`"}},"required":["vin"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Your Bowmark API key."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Bowmark-Key"}},"responses":{"NotFound":{"description":"No such site or function.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}},"schemas":{"RunEnvelope":{"type":"object","description":"What a run returns. `status` says whether the SCRIPT succeeded. A script that threw or paused for a login is still HTTP 200. Branch on `status`, not on the HTTP code.","required":["ok","status","result","logs","error","ms"],"properties":{"runId":{"type":"string","description":"Stable id for this run. Quote it in a support or `report` message."},"ok":{"type":"boolean","description":"False only when the run produced nothing usable."},"status":{"type":"string","enum":["ok","error","partial","needs_user"],"description":"`partial`: the result is real but some calls failed (see `incomplete`); `ok` stays true. `needs_user`: a person must sign in to a site first. Relay `meta.handoff.url` to them, then run again."},"egress":{"type":"string","enum":["default","link"],"description":"The egress the run was given, present only when the request asked for one. `link`: every request went through the caller's own Chrome (Bowmark Buddy)."},"result":{"description":"Whatever the script `return`ed. Any JSON value."},"logs":{"type":"array","items":{"type":"string"},"description":"Lines the script wrote with `log(...)`."},"error":{"type":["string","null"],"description":"Why the run failed, in plain words. Null on success."},"ms":{"type":"integer","description":"How long the script itself ran, in milliseconds."},"queuedMs":{"type":"integer","description":"How long the run waited for a worker before starting. Present only when it was a second or more."},"needs":{"type":"array","description":"The sign-ins this script is waiting on. Present when `status` is `needs_user`.","items":{"type":"object","required":["capability","provider","providerTitle","kind"],"properties":{"capability":{"type":"string"},"provider":{"type":"string"},"providerTitle":{"type":"string","description":"The site's name, to show a person."},"kind":{"type":"string"}}}},"incomplete":{"type":"object","description":"Present only when `status` is `partial`: which calls did not answer.","properties":{"summary":{"type":"string"},"totalCalls":{"type":"integer"}},"additionalProperties":true},"emptyHanded":{"type":"object","description":"Present when the script returned nothing while its calls returned rows, usually a filter that matched none of the site's own labels. Lists the label values the calls actually returned.","additionalProperties":true},"notes":{"type":"array","description":"Caveats a call attached to a complete answer. Never changes `status`.","items":{"type":"object","properties":{"path":{"type":"string"},"notes":{"type":"array","items":{"type":"string"}}}}},"meta":{"type":"object","properties":{"handoff":{"type":"object","description":"A single-use sign-in link for a person to open. Expires at `expiresAt`.","properties":{"ref":{"type":"string"},"url":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"}}},"concurrency":{"type":"object","description":"On a 429: how many runs are in flight and when to retry.","properties":{"limit":{"type":"integer"},"inFlight":{"type":"integer"},"retryAfterSeconds":{"type":"integer"}}}},"additionalProperties":true},"notice":{"type":"object","description":"Set when the account owner has not accepted the current Terms. Relay it to them.","additionalProperties":true}}}}}}