Discovery Contract — volkswagen (us)

The vetting gate between discovery and coding. This file is the human narrative + probe evidence; the authoritative gate state lives in the sidecar discovery-contract.gate.json, which public-api-implement checks via check_contract_gate.py. Keep this table in sync with the sidecar — every discovered endpoint/entity/FK in requirements must have a matching category:item gate, and every HARD row should read ✅ PASS or 🟡 OVERRIDE: <reason> (user-approved) before /public-api-implement volkswagen may run. A Postman row may instead read 📦 MANUAL-IMPORT: <path> when the Postman MCP was unavailable and the collection was exported for hand-import — that state passes the gate but stays flagged. Probe markdown blocks are pasted in verbatim by public-api-contract-test.

• OEM / market: volkswagen / us
• Discovered: 2026-06-10
• Gate status: ✅ hard gates refreshed after stale US catalogue finding · 📦 Postman collection exported for manual import

Gate summary

#	Gate	Entity / param	Status	Evidence
1	Pagination contract	inventory	✅ PASS	live 2026-06-24 — brand-level meta.resultNumber=68,672, pageMax=5,723; page 2 disjoint from page 1; last page = exact remainder. Completeness certified on t_model=BQAM slice: 1,839/1,839 across 154 pages
2	Enumerator (model)	models	✅ PASS	MOFA model-overview — 10 current US carlines (captured-live fixture; MOFA needs SPA-minted token)
3	Enumerator (year)	models	✅ PASS	MOFA model-overview — trim engines expose key.modelYear=2026
4	Enumerator (trim)	models	✅ PASS	MOFA model-overview — 43 trim-engine key.modelId across 32 trims
5	Enumerator (dealer)	dealers	🟡 OVERRIDE	Single national call returns all 626 dealers (live 2026-06-24); no enumeration param exists
6	Multi-value filter	inventory	⚪ N/A	no model filter is used; brand-level request covers all new VW inventory
7	Body shape / bot-block	inventory	✅ PASS	body_shape_probe — no bot-block, JSON always
8	Body shape / bot-block	features (configurator)	✅ PASS	body_shape_probe — /vcso/configStart returns JSON, no bot-block; 0/5 non-JSON responses
9	Data quality / plausibility	inventory	✅ PASS	data_quality_probe — 5 records, all fields populated
10	Data quality / plausibility	dealers	✅ PASS	data_quality_probe — 3 records, all fields populated
11	Data quality / plausibility	models	✅ PASS	refreshed fixture — 43 current MY2026 trim-engine rows with MSRP
12	Data quality / plausibility	features	✅ PASS	refreshed fixture — /vcso/configStart returns 280 features for MY2026 CA33PZ
13	Cross-source identity key	inventory→dealers	✅ PASS	cars[].dealer.key strip "USA" prefix == dealers[].id (12/12 live)
14	Cross-source identity key	inventory→models	✅ PASS	cars[].salesModelCode == MOFA engine key.modelId (partial: ~75% resolve; carlineId is 1:many so not viable as FK)
15	Cross-source identity key	inventory→features	✅ PASS	via salesModelCode → model → configStart features; color bridging via exterior_color name match adds ~33% coverage
16	Cross-source identity key	features→models	✅ PASS	vehicleConfiguration.modelKey == MOFA engine key.modelId
17	Real fixture (no synthetic)	inventory	✅ PASS	tests/data/gsl_inventory_sample.json
18	Real fixture (no synthetic)	dealers	✅ PASS	tests/data/dcc_dealers_sample.json
19	Real fixture (no synthetic)	models	✅ PASS	tests/data/mofa_models_sample.json
20	Real fixture (no synthetic)	features	✅ PASS	tests/data/configurator_features_sample.json
21	Postman record	inventory	📦 MANUAL-IMPORT	postman/volkswagen-us.postman_collection.json
22	Postman record	dealers	📦 MANUAL-IMPORT	postman/volkswagen-us.postman_collection.json
23	Postman record	models	📦 MANUAL-IMPORT	postman/volkswagen-us.postman_collection.json
24	Postman record	features	📦 MANUAL-IMPORT	postman/volkswagen-us.postman_collection.json
25	Freshness / live-site parity	models	✅ PASS	Old /viso/catalogue US tenant returned stale MY2024/2025 rows; MOFA builder endpoint returns current MY2026
26	Freshness / live-site parity	features	✅ PASS	/vcso/configStart reprobed with MOFA-derived modelYear=2026; response echoes MY2026

Per-entity endpoints

Entity	Endpoint (method + URL)	Auth / protocol	Fixture	Notes
inventory	GET <gsl_base_url>/bff/car/search	oneapiKey query param	gsl_inventory_sample.json	Brand-level new inventory; omit t_model; page param works
dealers	GET https://v3-81-9.ds-us.dcc.feature-app.io/bff-search/dealers	lufthansaApiKey query param	dcc_dealers_sample.json	Single call, 626 dealers (live 2026-06-24), no pagination/enumeration
models	GET https://v1-548-2.mofa.feature-app.io/bff/model-overview	oneapiKey query param	mofa_models_sample.json	Current VW US builder source; params/dataVersion derived from https://www.vw.com/en.global-config.json; old /viso/catalogue US tenant is stale
features	GET https://oneapi.volkswagen.com/vcso/configStart	x-api-key: Ox5AegtsLDecFmKHxYdf599VKBCpHsX4 header	configurator_features_sample.json	params: modelKey, modelYear, carlineKey, salesgroupKey, trimName, tenant=ihdcc-vw-us-en, cacheKey; returns vehicleCatalogue.features[] (280 features) + vehicleCatalogue.categories + vehicleConfiguration

Cross-source identity / FK alignment (HARD)

Value-matched (not name-matched) join keys, from probe + explore evidence.

FK	Referencing entity.field	Target entity.field	Example value	Verified
inventory→dealers	cars[].dealer.key (strip "USA" prefix)	dealers[].id	"USA06457" → "06457"	✅ 12/12 live
inventory→models	cars[].salesModelCode	MOFA engine key.modelId	"CA37PZ" == "CA37PZ"	✅ partial (~75%)
inventory→features (extensions)	model.mbv.extension tokens → G{tok}{tok}	configurator feature.code	"P16" → "GP16P16"	✅
inventory→features (color)	color.out.value (exterior_color name)	configurator feature.name	"Opal White" == "Opal White"	✅ 13/17 colors
features→models	vehicleConfiguration.modelKey	MOFA engine key.modelId	"CA33PZ"	✅

FK note (2026-06-24). salesModelCode is the correct FK for inventory→models. Some stock-only or older codes (~25%) do not appear in the current MOFA model overview — this is expected partial resolution, not a defect. carlineId was considered but rejected: it is one level higher in the hierarchy (one carlineId = many model codes, e.g., Atlas 31691 has 7 model_codes), making it unsuitable as a precise FK. The stock-only/older-code gap is accepted; inventory-derived model rows were intentionally not retained because they carry too little detail to be useful.

Color bridging (2026-06-24). GSL inventory uses 2-digit color codes (e.g., "04") that do not match configurator F14 codes (e.g., "F14 0R0R"). However, the color name is an exact match: GSL color.out.value = "Opal White" == configurator feature.name = "Opal White". A second FK exterior_color>name resolves the color feature_id for 13/17 (76%) of distinct inventory colors, adding ~33% feature coverage. The 4 unmatched colors are older/discontinued model-year colors not in the current configurator.

Probe evidence

0. Freshness correction — models/features

The initial discovery used VW OneAPI /viso/catalogue/* for US product data. That endpoint still returns HTTP 200, but its US tenant no longer tracks the current VW US builder and returned stale model years (2024/2025). The live builder page (/en/builder.html) uses the MOFA model-overview BFF instead:

• GET https://v1-548-2.mofa.feature-app.io/bff/model-overview
• Request parameters and serviceConfigEndpointToken are derived from https://www.vw.com/en.global-config.json.
• The refreshed fixture contains 10 carlines, 34 trims, 43 trim-engine model rows, and only modelYear=2026.
• The OneAPI configurator /vcso/configStart remains usable for full features when driven by MOFA model keys and modelYear=2026.

VERDICT: PASS — use MOFA for current model/trim/year enumeration; use /vcso/configStart only after MOFA supplies modelKey, modelYear, carlineKey, salesgroupKey, and trimName.

1. Pagination contract — inventory

Pagination contract — ✅ PASS (live 2026-06-24)

• Endpoint: GET https://v3-116-1.gsl.feature-app.io/bff/car/search
• Contract: page (1-based) + pageitems, size 12. pageitems is hard-capped at 12 by the API (requests for 100/500 still return meta.pageItems=12).
• Termination: short/empty page (or page >= meta.pageMax).
• Filter ablation: removing t_model preserves scope (t_cartype=N, VW brand, US) and returns complete brand-level new inventory. Required params include endpoint (the serviceConfigEndpoint JSON) and dataVersion from en.global-config.json.
• Brand-level completeness (live): meta.resultNumber=68,672, meta.pageItems=12, meta.pageMax=5,723. Page 2 is disjoint from page 1 (0 overlap → page honored). Page 5,723 returned exactly 8 cars = 68,672 - (5,723 - 1) * 12 → paging reaches the reported total, no silent cap.
• Full-pagination certification ran on a low-volume slice t_model=BQAM (pageitems is capped so the brand-level 5,723 pages exceed any probe ceiling): pagination_probe fetched 1,839/1,839 unique vins across 154 pages, reached the natural end, param_ignored=false. Same page/pageitems mechanism drives the brand-level fetch.

{"probe":"pagination","passed":true,"pages_fetched":154,"unique_records":1839,"reported_total":1839,"reached_end":true,"param_ignored":false,"page_style":"page"}

VERDICT: PASS

---

2–5. Enumerators (model / year / trim / dealer)

Enumerator (model) — ✅ PASS

• GET https://v1-548-2.mofa.feature-app.io/bff/model-overview enumerates 10 current VW US carlines in payload.models[]: Atlas, Atlas Cross Sport, Tiguan, Taos, ID.4, Jetta, Jetta GLI, Golf R, Golf GTI, and ID. Buzz.
• This is the same model overview source used by https://www.vw.com/en/builder.html.
• Request parameters and the MOFA feature-app host are resolved from https://www.vw.com/en.global-config.json.

VERDICT: PASS

---

Enumerator (year) — ✅ PASS

• MOFA trim engines enumerate model year at payload.models[].children[].data.engines[].key.modelYear.
• The refreshed fixture contains only 2026 model-year rows for the current US builder.

VERDICT: PASS

---

Enumerator (trim) — ✅ PASS

• MOFA payload.models[].children[] enumerates trims.
• Each trim includes data.engines[]; each engine has the stable model identity tuple: key.carlineId, key.salesgroupId, key.trimId, key.modelId, and key.modelYear.
• The refreshed fixture has 34 trims and 43 trim-engine model rows.

VERDICT: PASS

---

Enumerator (dealer) — 🟡 OVERRIDE

• The DCC endpoint GET https://v3-81-9.ds-us.dcc.feature-app.io/bff-search/dealers returns all 626 US VW dealers in a single call (live 2026-06-24). There is no fan-out enumeration parameter. The single call is the complete national dataset.

VERDICT: OVERRIDE — dealer enumeration is a single national call; no fan-out param exists

---

6. Multi-value filter — inventory

Multi-value filter — ⚪ N/A

• No multi-value model filter is used.
• Discovery proved the broader brand-level request without t_model returns the complete new VW inventory population, so there is no model fan-out and no combined-filter mode.

VERDICT: N/A

---

7–8. Body shape / bot-block

Body shape / bot-block (inventory) — ✅ PASS

• Endpoint: GET <gsl_base_url>/bff/car/search (https://v3-116-1.gsl.feature-app.io on 2026-06-17)
• Every 2xx response with a realistic UA parsed as JSON. Default-UA block rate 0%; realistic-UA block rate 0%.
• UA is not required. No bot-block protection detected.

VERDICT: PASS

---

Body shape / bot-block (configurator) — ✅ PASS

• Endpoint: GET https://oneapi.volkswagen.com/vcso/configStart
• Auth: x-api-key: Ox5AegtsLDecFmKHxYdf599VKBCpHsX4 (discovered via chrome-devtools network inspection of Build & Price configurator)
• Required params: tenant=ihdcc-vw-us-en, modelKey=CA33PZ, carlineKey=31691, salesgroupKey=34910, trimName=SE, cacheKey=<from /cks/cachekey/ihdcc-vw-us-en>
• Every 2xx response with a realistic UA parsed as JSON. Default-UA block rate 0%; realistic-UA block rate 0%.
• UA is not required. No bot-block protection detected.
• Response structure: vehicleCatalogue.features[] (280 features for Atlas SE CA33PZ), vehicleCatalogue.categories (additional, exterior, interior, standardEquipment, wheel), vehicleConfiguration (modelKey, modelYear, prices)
• Feature fields: code, name, isExterior, isInterior, isStandard, isSelectable, isIncluded, isVisible, isPackageFeature, packages, packageFeatures, prices[], mediaAssets[]
• Previous endpoint /viso/catalogue/models/{code}/vehicleCatalogue/features was removed; vcso/configStart is the replacement (confirmed via live browser traffic, 2026-06-10)
• Fixture updated: tests/data/configurator_features_sample.json — 293KB, 280 features, live call

{
  "probe": "body_shape",
  "passed": true,
  "requests_per_batch": 5,
  "no_ua_nonjson_pct": 0.0,
  "with_ua_nonjson_pct": 0.0,
  "ua_required": false,
  "no_ua_errors": 0,
  "with_ua_errors": 0
}

VERDICT: PASS

---

9–12. Data quality / plausibility

Data quality (inventory) — ✅ PASS

• 5 records assessed; every critical field is populated and plausible.

Field	Rule	Implausible %	Distinct	Verdict
vin	nonempty	0%	5	✅ ok
configurationPrice	nonempty	0%	5	✅ ok
carline	nonempty	0%	2	✅ ok
dealer.key	nonempty	0%	3	✅ ok

VERDICT: PASS

---

Data quality (dealers) — ✅ PASS

• 3 records assessed; every critical field is populated and plausible.

Field	Rule	Implausible %	Distinct	Verdict
id	nonempty	0%	3	✅ ok
coordinates.0	nonempty	0%	3	✅ ok
coordinates.1	nonempty	0%	3	✅ ok

VERDICT: PASS

---

Data quality (models) — ✅ PASS

• Refreshed MOFA fixture extracts 43 trim-engine model rows. Every critical field is populated and plausible.

Field	Rule	Implausible %	Distinct	Verdict
key.modelId	nonempty	0%	43	✅ ok
key.carlineId	nonempty	0%	10	✅ ok
key.modelYear	nonempty	0%	1 (2026)	✅ ok

VERDICT: PASS

---

Data quality (features) — ✅ PASS (fixture-based)

• Refreshed /vcso/configStart fixture returns 280 MY2026 feature rows for CA33PZ. Every critical field is populated and plausible.

Field	Rule	Implausible %	Distinct	Verdict
code	nonempty	0%	280	✅ ok

• Note: the removed /vehicleCatalogue/features path is obsolete. The live /vcso/configStart endpoint is the current features source.

VERDICT: PASS

---

13–16. Cross-source identity keys

inventory→dealers: cars[].dealer.key (e.g. "USA06457") strips the "USA" prefix to get "06457", matching dealers[].id. Transform: dealer.key.removeprefix("USA"). Live 2026-06-24: 12/12 sampled inventory dealer keys resolved into the 626-dealer DCC national list.

inventory→models: cars[].salesModelCode matches MOFA key.modelId for ~75% of distinct inventory codes. The ~25% gap (BU42RS, BU51RS, DA16UZ) are stock-only or older codes not in the current MOFA builder — expected partial resolution. These inventory-only model codes are not backfilled because GSL carries too little model detail to create useful model records. carlineId is NOT suitable as an FK: it is one level higher (one carline = many model codes, e.g., Atlas 31691 has 7 model_codes).

inventory→features: Two resolution paths: (1) extension-based: model.mbv.extension tokens (e.g., P16) → G{tok}{tok} feature codes matched against configurator features per model_code; (2) color-name-based: color.out.value (exterior color name) matched against configurator feature.name per model_code, resolving the F14 color feature. Together these cover ~42% of inventory (up from ~9% with extensions alone).

features→models: vehicleConfiguration.modelKey (e.g. "CA33PZ") is a direct match to MOFA key.modelId, and vehicleConfiguration.carlineKey (e.g. "31691") matches MOFA key.carlineId; vehicleConfiguration.modelYear = "2026". /vcso/configStart is parameterized by MOFA keys, so this FK is sound by construction.

---

17–20. Real fixtures

• projects/ai_volkswagen/tests/data/gsl_inventory_sample.json — GSL inventory response-shape fixture
• projects/ai_volkswagen/tests/data/us/dcc_dealers_sample.json — captured from live DCC API (/bff-search/dealers), correlated to inventory dealer.key (national list = 626)
• projects/ai_volkswagen/tests/data/mofa_models_sample.json — captured from live MOFA /bff/model-overview, current MY2026 model overview
• projects/ai_volkswagen/tests/data/configurator_features_sample.json — captured from live OneAPI /vcso/configStart using MOFA-derived CA33PZ MY2026 inputs

---

23–27. Postman records

Postman MCP was unavailable, so the collection is exported for manual import:

• docs/content/oems/volkswagen/postman/volkswagen-us.postman_collection.json
• Includes concrete + parameterized requests for cache key, MOFA model overview, OneAPI configurator features, GSL inventory, and DCC dealers.

---

Overrides

Gate	OVERRIDE reason	Approved by
enumerator:dealer	Single national DCC call returns all 626 dealers (live 2026-06-24); no fan-out enumeration parameter exists	pending user approval

Blockers

None. The stale US catalogue was resolved by switching product discovery to MOFA. Inventory fan-out was eliminated by proving GSL returns complete brand-level new inventory when t_model is omitted.