{"openapi":"3.1.0","info":{"title":"Cars.com API (Bowmark)","version":"e833508f87ff","description":"Cars.com — the US new/used/certified car marketplace: for-sale inventory with dealer asking prices, one listing's full detail, a valuation for a car you already own, and per-model research (trims, specs, expert and owner reviews). Three functions are built: searching the inventory, reading one listing in full, and reading one year/make/model's research overview. A fourth — the cash-offer valuation — is built too: callers pass a VIN, a ZIP, and the caller-supplied identity the 2026-07-31 quote-flow ruling requires, and the function returns the trade-in offer and private-party value perseus published for the assigned local dealer.\n\nEvery function Bowmark has for Cars.com (cars.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/cars/search":{"post":{"operationId":"search","summary":"Searches Cars.com's live for-sale inventory the way its own shopping results page does — by ZIP and radius, new / used / certified-pre-owned, make, model, price, mileage — and returns the matching lis","description":"Searches Cars.com's live for-sale inventory the way its own shopping results page does — by ZIP and radius, new / used / certified-pre-owned, make, model, price, mileage — and returns the matching listing ids (each one is a getListing argument verbatim), the total match count across all pages, and the filter set the service actually applied.\n\nCalls `bowmark.providers.cars.search`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<carsSearch>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"type":"object","properties":{"zipCode":{"type":"string"},"radiusMiles":{"type":"number"},"stockType":{"anyOf":[{"const":"new"},{"const":"used"},{"const":"cpo"}]},"make":{"type":"string"},"model":{"type":"string"},"maxPrice":{"type":"string"},"minPrice":{"type":"string"},"maxMileage":{"type":"string"},"page":{"type":"number"},"pageSize":{"type":"number"},"sort":{"anyOf":[{"const":"BEST_MATCH_DESC"},{"const":"LIST_PRICE"},{"const":"LIST_PRICE_DESC"},{"const":"MILEAGE"},{"const":"MILEAGE_DESC"},{"const":"YEAR"},{"const":"YEAR_DESC"},{"const":"LISTED_AT"},{"const":"LISTED_AT_DESC"},{"const":"DISTANCE"}]}},"additionalProperties":true,"description":"TypeScript: `{ zipCode?: string; radiusMiles?: number; stockType?: 'new' | 'used' | 'cpo'; make?: string; model?: string; maxPrice?: string; minPrice?: string; maxMileage?: string; page?: number; pageSize?: number; sort?: 'BEST_MATCH_DESC' | 'LIST_PRICE' | 'LIST_PRICE_DESC' | 'MILEAGE' | 'MILEAGE_DESC' | 'YEAR' | 'YEAR_DESC' | 'LISTED_AT' | 'LISTED_AT_DESC' | 'DISTANCE' }`"}},"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/cars/getListing":{"post":{"operationId":"getListing","summary":"Reads one cars.com listing in full by its id (the uuid in a /vehicledetail/<id>/ url): VIN, asking price, mileage, year/make/model, stock number, CPO status, EPA highway mpg, the listing's ZIP and fir","description":"Reads one cars.com listing in full by its id (the uuid in a /vehicledetail/<id>/ url): VIN, asking price, mileage, year/make/model, stock number, CPO status, EPA highway mpg, the listing's ZIP and first-listed date, the site's own price badge, and the selling dealer.\n\nCalls `bowmark.providers.cars.getListing`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<carsListing>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"listingId":{"type":"string","description":"TypeScript: `string`"}},"required":["listingId"],"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/cars/getModelResearch":{"post":{"operationId":"getModelResearch","summary":"Reads Cars.com's research overview for one year/make/model: starting price (or, for a model year no longer on sale, the average listing price), body style, drivetrain, seating and mpg, the trim levels","description":"Reads Cars.com's research overview for one year/make/model: starting price (or, for a model year no longer on sale, the average listing price), body style, drivetrain, seating and mpg, the trim levels offered, the site's own aggregate consumer rating, its expert review's headline/pros/cons, and what changed for that model year — null/absent exactly where cars.com's own page shows nothing for it.\n\nCalls `bowmark.providers.cars.getModelResearch`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<carsModelResearch>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"type":"object","properties":{"make":{"type":"string"},"model":{"type":"string"},"year":{"type":"number"}},"required":["make","model","year"],"additionalProperties":true,"description":"TypeScript: `{ make: string; model: 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/cars/getVehicleValue":{"post":{"operationId":"getVehicleValue","summary":"Reads Cars.com's own cash-offer valuation for a car the caller already owns: the trade-in offer and the private-party value perseus computed for the dealer's assigned ZIP, with the dealer and mileage ","description":"Reads Cars.com's own cash-offer valuation for a car the caller already owns: the trade-in offer and the private-party value perseus computed for the dealer's assigned ZIP, with the dealer and mileage the offer was scoped to. Identity is required (caller-supplied, per the 2026-07-31 quote-flow ruling) so perseus has a person to assign the offer record to. The function NEVER calls contactDealer, optinDealer, acceptByCode, smsPictureRequest or media.create — the contact routes the 2026-08-06 standing decision names as the fence for a cash-offer appraisal.\n\nCalls `bowmark.providers.cars.getVehicleValue`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<carsVehicleValue>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"type":"object","properties":{"vin":{"type":"string"},"identity":{"$ref":"#/components/schemas/QuoteIdentity"},"postalCode":{"type":"string"},"mileage":{"type":"number"}},"required":["vin","identity","postalCode"],"additionalProperties":true,"description":"TypeScript: `{ vin: string; identity: QuoteIdentity; postalCode: string; mileage?: 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"}}}}}}}},"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}}},"QuoteIdentity":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"dob":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"}},"required":["firstName","lastName","dob","email","phone"],"additionalProperties":true}}}}