{"openapi":"3.1.0","info":{"title":"BMW USA API (Bowmark)","version":"e833508f87ff","description":"BMW US car shopping: the Build Your Own configurator and its option pricing, live VIN-level new and Certified Pre-Owned dealer inventory near a ZIP, the model lineup with trims and MSRP, current lease and finance offers, the dealer locator, plus recall lookup by VIN, accessories and owner's manuals.\n\nEvery function Bowmark has for BMW USA (bmwusa.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/bmwusa/buildVehicle":{"post":{"operationId":"buildVehicle","summary":"Runs BMW's own Build Your Own configurator for a model code (read off /all-bmws.html's build-your-own.html#/studio/{code} links) applying zero or more option codes (paint, wheels, trim, packages, indi","description":"Runs BMW's own Build Your Own configurator for a model code (read off /all-bmws.html's build-your-own.html#/studio/{code} links) applying zero or more option codes (paint, wheels, trim, packages, individual options) one at a time exactly as the site's own UI does, and returns the as-configured price — base price, destination & handling, each selected option's own incremental cost, and BMW's own computed total.\n\nCalls `bowmark.providers.bmwusa.buildVehicle`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<BmwusaBuiltVehicle>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"modelCode":{"type":"string","description":"TypeScript: `string`"},"optionCodes":{"type":"array","items":{"type":"string"},"description":"TypeScript: `string[]`"}},"required":["modelCode"],"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/bmwusa/searchCertifiedPreOwned":{"post":{"operationId":"searchCertifiedPreOwned","summary":"Searches BMW's live Certified Pre-Owned inventory near a 5-digit ZIP code, server-side scoped to CPO-only stock (BMW's own 'BMW Certified' facet — plain used cars are excluded), returning each match's","description":"Searches BMW's live Certified Pre-Owned inventory near a 5-digit ZIP code, server-side scoped to CPO-only stock (BMW's own 'BMW Certified' facet — plain used cars are excluded), returning each match's VIN, year, model, trim, mileage, exterior/interior colour, drivetrain, fuel type, asking price, photos and holding dealer. `options.radius` and `.limit` are sent to the site; `.model`/`.minYear`/`.maxYear`/`.maxPrice`/`.maxOdometer` filter the returned page client-side (BMW's own server-side price/mileage facets are pre-set buckets, not raw numbers, so this filters honestly rather than guessing bucket boundaries).\n\nCalls `bowmark.providers.bmwusa.searchCertifiedPreOwned`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<BmwusaCpoVehicle[]>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"zip":{"type":"string","description":"TypeScript: `string`"},"options":{"type":"object","properties":{"radius":{"type":"number"},"limit":{"type":"number"},"model":{"type":"string"},"minYear":{"type":"number"},"maxYear":{"type":"number"},"maxPrice":{"type":"number"},"maxOdometer":{"type":"number"}},"additionalProperties":true,"description":"TypeScript: `{ radius?: number; limit?: number; model?: string; minYear?: number; maxYear?: number; maxPrice?: number; maxOdometer?: number }`"}},"required":["zip"],"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/bmwusa/getModel":{"post":{"operationId":"getModel","summary":"Reads one BMW model's body-style page (path is the segment of the site's own /vehicles/...html URL, e.g.","description":"Reads one BMW model's body-style page (path is the segment of the site's own /vehicles/...html URL, e.g. 'x-models/x5', '2-series/coupe' — read off bmwusa.com's own navigation or sitemap.xml) and returns its series, model name, and every trim BMW currently sells on that page: each trim's own name, its build-your-own model code (the same code buildVehicle takes), 0-60 time, horsepower, starting MSRP (null when the site shows '--' — not yet published), engine type, drivetrain, transmission, fuel type, fuel efficiency (MPG or MPGe) and seating capacity.\n\nCalls `bowmark.providers.bmwusa.getModel`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<BmwusaModel>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string","description":"TypeScript: `string`"}},"required":["path"],"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/bmwusa/listOffers":{"post":{"operationId":"listOffers","summary":"Lists BMW's current US lease and finance offers for a 5-digit ZIP code (resolved server-side to a sales region, since the site's own offer objects carry per-region eligibility) — every model with an a","description":"Lists BMW's current US lease and finance offers for a 5-digit ZIP code (resolved server-side to a sales region, since the site's own offer objects carry per-region eligibility) — every model with an active offer, each with its own lease (monthly payment, term, MSRP, down payment, due-at-signing, allowed miles, loyalty credit) and/or finance (APR tiers, loyalty credit) terms, exactly as bmwusa.com's own /special-offers.html widget resolves them.\n\nCalls `bowmark.providers.bmwusa.listOffers`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<BmwusaOffersResult>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"zip":{"type":"string","description":"TypeScript: `string`"}},"required":["zip"],"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/bmwusa/listModels":{"post":{"operationId":"listModels","summary":"Lists BMW's current US lineup — every model BMW sells, with its bmwusa.com model-overview URL, body style, powertrain category (electric / plug-in hybrid / performance / gasoline) and starting MSRP ba","description":"Lists BMW's current US lineup — every model BMW sells, with its bmwusa.com model-overview URL, body style, powertrain category (electric / plug-in hybrid / performance / gasoline) and starting MSRP band — so an agent can resolve a person's vague 'a BMW SUV under $60k' into the specific models that exist, with their real prices, before looking up any one of them. Reads /all-bmws.html for the 49-card catalog, then fans out (concurrency 5) to each model-overview page for MSRP; pages with no trim table (BMW iX, certain M models) still appear in the result with null MSRPs and null body style rather than dropping the model.\n\nCalls `bowmark.providers.bmwusa.listModels`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<BmwusaModelListing[]>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"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}}}}}}