POST /v2/search. Takes a natural-language question and returns ranked, in-stock vehicles at a dealer.GET /v2/vehicles/vin/{vin}/similar. Takes an anchor VIN and returns the closest in-stock alternatives at the same dealer.POST /v2/match-score. Takes a shopper intent plus a list of VINs and returns each VIN’s score against the intent. Used to re-rank a shortlist when the shopper’s question evolves.
What vectors do, in plain terms
A vector is a list of numbers that encodes the meaning of a vehicle. Year, model, trim, body, options, description, and pricing context all collapse into a single point in a high-dimensional space. Vehicles that are conceptually similar end up close together in that space. A Buick Enclave and a Chevy Traverse, both three-row family SUVs, sit near each other regardless of whether they share any keywords. Vault encodes shopper questions the same way. “Something that turns heads” becomes a point in the same space. The match is the geometric distance between the question’s point and each vehicle’s point. Closer is more relevant. This is one fast operation per vehicle, which is why the endpoints stay sub-second on inventories of two thousand vehicles or more. The advantage over a SQL filter or keyword index is what gets matched.body = SUV returns every SUV in random order. “Something that turns heads” is not a column you can filter on. It is a direction in the vector space, and Vault finds the vehicles closest to that direction.
What Vault is, what it is not
Vault is production vector infrastructure. The encoding pipeline runs continuously: when a dealer’s scrape lands, new vehicles are encoded within seconds, updated vehicles are re-encoded, and sold vehicles are removed. The store reflects what is actually on the dealer’s lot right now. You do not host an embedding model, manage a vector database, or run a nightly indexer. Vault is not a chat backend. It does not generate text, route conversations, or hold user state. Those belong to the AI assistant on your side. Vault’s endpoints are tools that an LLM calls during a conversation. The boundary is firm: your LLM owns the user experience, Vault owns the retrieval.A note on score_threshold
POST /v2/search accepts an optional score_threshold between 0.0 and 1.0. It is a relevance floor: results scoring below the threshold are dropped before being returned.
For natural-language shopper questions (“fun to drive”, “good for my new dad”, “I tow a boat on weekends”), set it to 0.20. The endpoint defaults to 0.30, which is stricter and works for narrower spec-style lookups (a specific model, a trim, a color). Every POST /v2/search example below sets score_threshold: 0.20 explicitly.
All examples below use
dealership_id for compactness. You can substitute "dealership_url": "carlblackroswell.com" if you’d rather scope by URL.The example VINs and result snippets reflect real, live inventory at the time of writing. Dealer lots rotate. Specific VINs may have sold and specific top-result rankings may have shifted by the time you run these requests. The request shapes and response schemas are stable; the data is not.
GET /v2/vehicles/vin//similar
Takes a VIN. Returns the closest in-stock vehicles at the same dealer, ranked by similarity to the anchor’s encoded vector. Three patterns the endpoint handles cleanly: the shopper’s pick is over budget so they want the same model at a lower trim, the shopper wants a different model year of the same model, or the shopper’s pick just sold and the LLM needs a near-alternative to keep the conversation alive. Scores for/similar are high (typically 0.94 and above) because the comparison is between two rich vehicle vectors. Treat 0.94+ as “in the same conceptual neighborhood.”
1. Same-model price ladder
Shopper: “I love this S-Class but it’s a stretch for me.” Vault returns lower-priced in-stock S-Class alternatives.
Response (abbreviated)
2. Same-model trim ladder
Shopper: “I like this Encore GX but it’s just over what I want to spend.” Vault returns three trims of the same model at lower price points.
Response (abbreviated)
3. Cross-year alternatives
Shopper: “This 2025 GLE is more than I want to spend. Anything similar but less?” Vault returns same-model alternatives from earlier model years, ranked by similarity.
Response (abbreviated)
POST /v2/search
Takes a question and a dealer ID. Returns ranked, in-stock vehicles. The shopper’s actual words are fine: they do not need to be reformatted into make and model terms. Vault encodes the question and ranks every vehicle in the dealer’s inventory by relevance. Scores for/v2/search are low (typically 0.20 to 0.40). That is expected. The comparison is between a short question vector and a full vehicle vector, which are different shapes of object. Do not interpret 0.30 as “weak.” Read the relative ordering.
4. “I want my friends to be jealous”
Shopper: “I want my friends to be jealous when they see my new car.” Vault returns the dealer’s headline-grabbing inventory.
Top result
5. “I haul construction materials for work”
Shopper: “I haul construction materials for work.” Vault returns work trucks and cargo vans across new and used inventory.
Top results
6. “Looks expensive but isn’t”
Shopper: “I want something that looks expensive but isn’t.” Vault returns value-luxury trims that feel premium without the price tag.
Top results
7. “Something that turns heads”
Shopper: “I want something that turns heads.” Vault returns the dealer’s most visually striking inventory.
Top results
8. “Boring but practical”
Shopper: “I want something boring but practical, just gets me there.” Vault returns dependable, no-drama daily drivers.
Top results
POST /v2/search with hard filters
The endpoint accepts structured filters alongside the question:condition, make, year_min, year_max, price_min, price_max. The question controls ranking. The filters control the candidate pool. They compose: an LLM can pass a vague-sounding question and a hard budget cap in the same call.
9. “Fun to drive” under $40,000
Shopper: “I want something fun to drive but I have to stay under forty grand.” Vault returns sport-trim and performance-oriented cars priced at or under $40,000.
Top results
10. “Luxury feel” GMC only
Shopper: “I want a luxury feel, but I’m a GMC person.” Vault returns the dealer’s top-tier GMC trims (Denali Ultimate Sierra and Yukon).
Top results
POST /v2/match-score
Takes a question and a caller-supplied list of VINs (up to 25). Returns each VIN’s score against the question, anin_stock flag, and an optional price_fit against price_min and price_max. The vehicles are not re-encoded: Vault reuses each one’s already-stored vector. One embedding call for the question, one bulk vector retrieve, comparison in memory.
Why this endpoint exists separately from /v2/search: in an agentic flow, the customer’s LLM often holds a shortlist from a prior turn (a /v2/search result, a previously-shown set, a hand-picked group) and wants to re-rank just that shortlist when the shopper adds a constraint. /v2/match-score is the right tool for that re-rank. /v2/search is the right tool when the candidate pool is the dealer’s whole inventory.
Scores for /v2/match-score are in the same low natural-language range as /v2/search (typically 0.20 to 0.40). Same reason: question vector versus vehicle vector. Compare relative ordering, not absolute values.
Same VINs, different intents, different ordering
The reason this endpoint belongs in the toolkit is that the score is a direct function of the intent. Hold the candidate set fixed; vary the intent; the ordering changes. The next two examples use the same five VINs to make that point explicit.Intent A: “family friendly with good cargo space” (budget 40,000)
The Encore GX, a compact crossover priced inside the budget, comes back at the top. The S-Class drops to fourth.
Response
Intent B: same VINs, “something that feels luxurious and turns heads” (budget 100,000)
The S-Class comes back at the top. The Encore GX drops to second.
Response (abbreviated)
The bad VIN (
INVALIDXXXXX00001) appears in both responses with match_score: null, vehicle: null, and in_stock: false. The caller can rely on this shape to confirm a requested VIN is no longer available without parsing error fields.price_fit is an independent signal from match_score. The S-Class wins on luxury intent even though it is out of budget (over_range). The caller’s LLM decides whether to surface, filter, or footnote the out-of-range result. Vault returns both signals; it does not make that decision for you.
A worked flow: /v2/search then /v2/match-score
This is what an agentic chat looks like when the customer’s LLM uses both endpoints in one conversation. The dealer here is Ewing Buick GMC (dealership_id = 2).
Step 1. Shopper opens broad. The LLM calls /v2/search.
The shopper types something general into the on-site assistant. The LLM passes the question through to Vault, scoped to the dealer.
Step 2. The LLM shows the shortlist. The shopper adds a constraint.
The LLM renders the top three to five results in the chat. The shopper does not pick a single car, but they read the list and react: low miles, daily commute, not a cargo van. The LLM’s enriched intent becomes “family SUV with low miles for a daily commute,” and the budget tightens to 45,000.Step 3. The LLM calls /v2/match-score on the same VINs with the enriched intent.
The candidate pool is the shortlist, not the dealer’s whole inventory. The LLM does not re-fetch and does not pay for a new search. It calls /v2/match-score with the VINs it already has and the now-richer intent.
Top result
What Vault does. What the customer’s LLM does.
Vault: encodes vehicles, stores vectors, serves the three retrievals, keeps the store in sync with the dealer’s lot. That is the entire surface area. The customer’s LLM: decides when to call/v2/search, when to call /v2/match-score, holds the conversation, holds the shortlist between turns, renders responses, asks clarifying questions, and presents the dealership UI. None of that is in Vault.