Skip to main content

Volkswagen US — API Explore Summary

Market: US | Originally discovered: 2026-06-10 | Refreshed: 2026-06-17 | Re-validated live: 2026-06-24

Current Source Selection​

The initial discovery found a working VW OneAPI /viso/catalogue/* product tenant, but that US tenant is stale for current product data. It returns HTTP 200 with older model years, while the public VW US builder now uses MOFA for current MY2026 model overview data. Use the sources below.

EntitySourceNotes
Global configGET https://www.vw.com/en.global-config.jsonRuntime source for feature-app hosts, API keys, service endpoint token, and data versions
Models / trims / yearsGET <mofa_base_url>/bff/model-overviewCurrent VW US builder source; returns 10 carlines, 34 trims, 43 trim-engine model rows, all MY2026
FeaturesGET https://oneapi.volkswagen.com/vcso/configStartDriven by MOFA modelId, modelYear, carlineId, salesgroupId, trimId, and fresh cache key
InventoryGET <gsl_base_url>/bff/car/searchPaginated VIN inventory; omit t_model to collect all new VW inventory
DealersGET <dcc_base_url>/bff-search/dealersSingle national US call; returns 625 dealers

Freshness re-validation (2026-06-24). The live VW US builder (https://www.vw.com/en/builder.html) renders the same 10 current MY2026 carlines with MSRP (Atlas $39,310, Atlas Cross Sport $38,300, Tiguan $30,805, Taos $26,500, ID.4 $45,095, Jetta $23,995, Jetta GLI $33,745, Golf R/GTI, ID. Buzz) — matching the MOFA fixture. GSL inventory and DCC dealers were re-issued headless via httpx and returned live MY2026 data. The MOFA /bff/model-overview proxy now additionally requires a runtime serviceConfigEndpointToken minted by the SPA (not a flat config field), so the raw MOFA fetcher must derive it as the builder does; the captured fixture remains the authoritative shape.

Feature-app base URLs and keys must be resolved from en.global-config.json at runtime. On 2026-06-17 the observed bases were (DCC bumped to v3-81-9.ds-us.dcc by 2026-06-24):

AppBase URL
MOFAhttps://v1-548-2.mofa.feature-app.io
GSLhttps://v3-116-1.gsl.feature-app.io
DCChttps://v3-81-1.ds.dcc.feature-app.io (US requests use .ds-us.)

Runtime Tokens​

en.global-config.json provides:

  • spaAsyncConfig.serviceConfigEndpoint — JSON blob for MOFA/GSL/DCC requests.
  • spaAsyncConfig.dataVersions.serviceConfigsVersion — GSL dataVersion.
  • Feature-app entries for MOFA/GSL/DCC base URLs and API keys.

Fetch the OneAPI cache key before /vcso/configStart:

GET https://oneapi.volkswagen.com/cks/cachekey/ihdcc-vw-us-en
x-api-key: 1AvAgztRZs6LdqjOULN1u7WTskbc5AnS

Response shape: {"key":"..."}.

Models​

Endpoint: GET <mofa_base_url>/bff/model-overview

Core params: countryCode=US, currency=USD, language=en, mode=standalone, oneapiKey, serviceConfigEndpointToken, cacheBuster, dataVersion, ssr=true.

Response path: payload.models[]

Identity: trim engine key.modelId, e.g. CA33PZ.

Current carlines: Atlas, Atlas Cross Sport, Tiguan, Taos, ID.4, Jetta, Jetta GLI, Golf R, Golf GTI, ID. Buzz.

Inventory​

Endpoint: GET <gsl_base_url>/bff/car/search

Required params: t_cartype=N, sort=PRICE_SALE, sortdirection=ASC, page, pageitems=12, country=US, language=en, market=passenger, oneapiKey, dataVersion, endpoint.

Pagination: page is 1-based. The API returns 12 rows per page; meta.pageMax and meta.resultNumber describe total coverage.

Filter ablation: Removing t_model returns complete brand-level new VW inventory. Live check on 2026-06-24: meta.resultNumber=68672, meta.pageItems=12, meta.pageMax=5723 (reproduced headless via httpx; numbers drift from the 2026-06-17 68885/5741 as stock turns over — confirms a live, non-cached source). No product fan-out is needed for raw inventory.

Records path: cars · id field: cars[].vin (also cars[].carid) · total path: meta.resultNumber.

Quality-critical fields: cars[].vin / cars[].carid non-empty; cars[].configurationPrice non-zero (live sample $25,270); cars[].salesModelCode non-empty.

FKs (re-verified live 2026-06-24): cars[].salesModelCode (e.g. BU52RS, CA37PZ) joins MOFA engine key.modelId; cars[].dealer.key (e.g. USA22221) strips the USA prefix to join DCC dealers[].id (22221). Both FKs resolve against the captured fixtures (inventory dealers 22221/05219/05073 all present in the DCC fixture; codes BU52RS/CA37PZ both present in the MOFA fixture).

Features​

Endpoint: GET https://oneapi.volkswagen.com/vcso/configStart

Required params: tenant=ihdcc-vw-us-en, cacheKey, modelKey, modelYear, carlineKey, salesgroupKey, trimName.

MOFA supplies all model/trim/year identifiers. /vcso/configStart returns vehicleCatalogue.features[], vehicleCatalogue.categories, and vehicleConfiguration. The removed /vehicleCatalogue/features path is obsolete.

Dealers​

Endpoint: GET <dcc_base_url>/bff-search/dealers (live base on 2026-06-24: https://v3-81-9.ds-us.dcc.feature-app.io)

Params (live-verified 2026-06-24):

  • lufthansaApiKey=h0CQWvPYSBvp5KYXUpRU4FpZrnl0tZx1 (DCC-specific key, not the shared oneapiKey)
  • serviceConfigEndpoint — the structured endpoint JSON from en.global-config.json spaAsyncConfig.serviceConfigEndpoint ({endpoint:{type:publish,country:us,language:en,content:onehub_pkw,envName:prod},signature:...})
  • query JSON with type=DEALER, language=en-US, countryCode=US, dealerServiceFilter=[], contentDealerServiceFilter=[], usePrimaryTenant=true, name=" ".

Single national call returns the full US VW dealer list (626 on 2026-06-24, reproduced headless via httpx). Response shape: top-level dealers[] + bffLoggerCalls; there is no record-count/total field — coverage is len(dealers). No pagination or dealer enumerator is needed.

Records path: dealers · id field: dealers[].id · total path: none.

Quality-critical fields: dealers[].coordinates is [latitude, longitude] (verified live: Gilbert AZ [33.29, -111.76], Pensacola FL [30.41, -87.28]) — all non-zero, in-range; dealers[].id non-empty.

Fixtures​

Bucketed by market under tests/data/us/ (registered as *_sample fixtures in tests/conftest.py):

  • projects/ai_volkswagen/tests/data/us/global_config_sample.json — structural runtime config (endpoint/signature/dataVersions match live; api-key values are placeholders, real keys in the contract).
  • projects/ai_volkswagen/tests/data/us/mofa_models_sample.json — full MOFA /bff/model-overview capture; payload.models[], 48 trim-engine key.modelId rows, all MY2026.
  • projects/ai_volkswagen/tests/data/us/gsl_inventory_sample.json — live GSL /bff/car/search capture (2026-06-24), 3 cars across 3 distinct dealers + full meta, truncated from pages 1/2000/4000 for dealer/model diversity.
  • projects/ai_volkswagen/tests/data/us/configurator_features_sample.json — OneAPI /vcso/configStart capture; vehicleCatalogue.features[] (280), modelKey CA33PZ MY2026.
  • projects/ai_volkswagen/tests/data/us/dcc_dealers_sample.json — live DCC /bff-search/dealers capture (2026-06-24), 3 dealers correlated to the inventory fixture's dealer.key values.

All four cross-source FK joins resolve against these fixtures (inventory→dealers, inventory→models, features→models).

Contract Notes​

  • Product freshness is a hard gate. A working API that returns stale model years is a wrong endpoint.
  • Before accepting any product fan-out parameter as required, remove it and prove whether the broader request already returns complete scoped data. VW inventory does.
  • Static OEM-internal fanout lists or mapping dicts are not acceptable. If fanout is truly needed, derive it from live upstream raw assets.