{ "openapi": "3.1.0", "info": { "title": "VehiclesDB API", "version": "v1", "summary": "Resolve any vehicle string to a canonical id — then pull the full record, the imagery and the plate formats behind it.", "description": "Messy vehicle data in, canonical vehicle data out.\n\nVehiclesDB is the open, canonical dataset of the world's vehicles — make/model\nrecords built from the official registers of 18 countries and published free under\nCC-BY-4.0 — plus the resolution engine and the curated enrichment built on top of\nit. This API is how you call all of it.\n\n**Free to evaluate:** [create an account](https://vehiclesdb.com/users/sign_up), mint a\nkey, and you start with 100 credits. It is a one-time grant, not a monthly\nallowance — there is no refill, and the credits are yours until you spend them.\n\n## The endpoints, in the order most integrations need them\n\n### 1. `POST /resolve` — normalization-as-a-service\n\nThe endpoint that does the hard part. A registry row, an insurance policy line, a\nmarketplace listing title — `\"MERCEDES-BENZ | 300 TDT\"` — comes back as a canonical\nid (`car/mercedes-benz/300-tdt`) with a confidence, ranked `alternates`, and\n`resolved_via`: the ordered audit trail of every alias, fold and id migration the\ninput passed through. Store that trail beside the id you keep and every resolution\nstays explainable years later.\n\nResolve once, store the id, and every other endpoint becomes a lookup.\n\n### 2. Vehicle records — `GET /vehicles/{kind}/{make_slug}/{model_slug}/full`\n\nEverything we hold on one model. **Open on every plan:** names, taxonomy, body type,\nper-country register evidence, popularity and rarity, published aliases, `former_ids`\n(check these before assuming a stored id vanished), year evidence, and the `era`\nbadge. **Paid plans add** the curated enrichment: production runs, variant and trim\ntaxonomy, reference links, related models, register-observed powertrain counts,\nmake-level facts. When your plan doesn't include it, the\nresponse says so out loud — `\"enrichment\": null, \"enrichment_gated\": true` — instead\nof quietly dropping fields.\n\n### 3. Vehicle images — `GET /vehicles/{kind}/{make_slug}/{model_slug}/images`\n\nStudio-style, colour-accurate renders addressed by the same canonical ids, in the\n14-colour VehiclesDB palette. The variant URLs in the response are **signed and\nkey-free** — put them straight in ``; your key never reaches a browser.\n\n### 4. License plates — `GET /plates/{code}` and `GET /plates/{code}/match`\n\nEvery registration series a jurisdiction has issued — pattern, period, vehicle\ncategories, statutory colours, a 1:1 SVG of the design — plus a matcher that says\nwhether a registration is valid there, formats it as issued, and names the series it\nbelongs to. Sourced from statutes and official registers, never scraped.\n\n### 5. `GET /me` — is my key working?\n\nThe one call that never spends a credit. It answers with the key's own identity —\nwhich key it is, which workspace and plan it bills, how many credits are left — so\nyou can tell a valid key from the RIGHT key. Point your health checks here.\n\n## Authentication\n\nEvery `/api/v1` endpoint takes a bearer token. Mint keys at\n[vehiclesdb.com/settings/api-keys](https://vehiclesdb.com/settings/api-keys):\n\n```\nAuthorization: Bearer vdb_sk_your_key\n```\n\nYou get two kinds of key, and the names say where each one lives. Your\n**private key** (`vdb_sk_`) is like a password: keep it on your server, use it\nfor everything below, and know that it spends your credits. Your **public key**\n(also called a publishable key, `vdb_pk_`) is the one you may put in a website\nwhere anyone can see it — it only opens the free Dropdown Data endpoints and\nspends nothing, and you can lock it to your domains in Settings. Never put a\nprivate key in a browser; nothing this API returns embeds one.\n\n## Locking a key down\n\nEvery key can carry a lock that says where it may be used from, and the lock\nis enforced during authentication itself, on every request:\n\n- A **public key** can be locked to your websites. We check the browser's\n `Origin` header (or `Referer` when `Origin` is absent) against your list.\n Exact hosts and `*.subdomain` wildcards work; matching ignores case and\n ports. A domain you list covers its `www.` form too (and the other way\n round), but other subdomains must be listed or wildcarded. A request\n from anywhere else answers `403` with\n `{\"error\": \"origin_not_allowed\"}`, plus the host we read from your\n request in `origin` (`null` when it sent neither header).\n- A **private key** can be locked to your servers' IP addresses or CIDR\n ranges. A request from outside them answers `403` with\n `{\"error\": \"ip_not_allowed\"}`.\n\nThe lock fails closed: a locked public key with no readable `Origin` or\n`Referer` is refused. Browsers send those headers by themselves, so your\nwebsite never notices — but a terminal does not, so when testing a locked\nkey with curl, say it yourself:\n\n```\ncurl https://vehiclesdb.com/api/v1/makes -H \"Authorization: Bearer vdb_pk_your_key\" -H \"Origin: https://yoursite.com\"\n```\n\nAn empty list means the key works from anywhere. A key whose stored lock\ncannot be verified at all answers `403` with\n`{\"error\": \"restriction_misconfigured\"}` rather than waving the request\nthrough.\n\n## Credits\n\nOne wallet across the whole surface, and each endpoint spends from it according to\nhow much work it is:\n\n| Endpoint | Credits |\n| --- | --- |\n| `GET /me` | free, always |\n| Dropdown Data (`/catalog`, `/makes`, `/makes/{slug}`, `/makes/…/models`, `/search`, `/makes/…/logo`) | free, always (public key) |\n| `POST /resolve` | 1 |\n| `GET /vehicles/…/images` | 1 |\n| `GET /plates/{code}/match` | 1 |\n| `GET /vehicles/…/full` | 2 |\n| `GET /plates/{code}` | 5 |\n\nThe two dearer ones are the two bulk reads: the full record is the deepest single\nanswer we serve, and a jurisdiction returns an entire plate-format corpus in one\ncall. Batch endpoints, when they land, spend per input rather than per call — the\nunit is the work, not the round trip.\n\nWork we couldn't do is free — malformed requests (`422`) and unknown ids or\njurisdictions (`404`) never spend a credit. An honest `\"match\": null` from\n`/resolve` does: the ladder ran either way, and knowing there is no good answer is\nworth as much as a hit.\n\nThe wallet belongs to your organization. Run it down and you get a `402` carrying\nyour balance and the self-serve top-up packs — no surprise invoice, no mid-month\nhard cut. A subscription refills your balance to the plan's allowance each period, so\nunspent subscription credits expire at the refill rather than stacking up. Credit\npacks are different: bought outright, and they never expire. Tiers and packs:\n[vehiclesdb.com/pricing](https://vehiclesdb.com/pricing).\n\n## Attribution travels in the payload\n\nEvery successful response carries an `attribution` object:\n\n```json\n\"attribution\": {\n \"source\": \"VehiclesDB\",\n \"url\": \"https://vehiclesdb.com\",\n \"license\": \"Identity layer: CC-BY-4.0; enrichment/resolution: proprietary…\",\n \"dataset_version\": \"2026.10.3\"\n}\n```\n\nIt is part of the data, not decoration: pass a response through your own system and\nthe credit travels with it. Don't strip it — the\n[API Terms](https://vehiclesdb.com/legal/api-terms) require redistributors to carry\nthe fields per record.\n\nThe object is **omitted entirely** on plans carrying the attribution waiver\n(Scale and Enterprise) — ToS §10.3, and the only thing that ever removes it. If you\nparse these responses, treat `attribution` as optional and never as a marker of\nsuccess: errors have never carried it either, because an error is nobody's content.\n\n`dataset_version` pins the answer to a dataset release, so what you got today is\nreproducible tomorrow.\n\n## Errors\n\nErrors are small, machine-readable JSON with a stable `error` string:\n\n```json\n{ \"error\": \"insufficient_credits\", \"message\": \"…\", \"balance\": 0 }\n```\n\n`401` missing or invalid key · `402` out of credits (carries your balance and the\npacks that fix it) · `404` unknown id or jurisdiction · `422` malformed request ·\n`429` rate limited. Branch on `error`, show `message` to humans.\n\n**`402` and `429` mean opposite things.** A `402` says the wallet is empty: top up or\nwait for the refill. A `429` says you are going too fast — the ceiling is\n600 requests per 1 minute and your credits are untouched, so wait out `Retry-After` and\ncarry on. Retrying a `402` straight away gets you nowhere; giving up on a `429`\nthrows away credits you still have.\n\n## Honest fallback\n\nThe rule the whole dataset is built on: **when we don't know, we say so.** We never\nguess to look complete.\n\n- `POST /resolve` refuses to claim a match below a confidence floor of `0.30`. You\n get `\"match\": null` and ranked `alternates` to put in front of a human, not a\n plausible wrong id.\n- Images fall back to a colour we have actually rendered, and the response tells you\n both what you asked for (`requested_color`) and what you got (`color`).\n- Plate colours come back `null` where the statute doesn't state them.\n- Gated fields are labelled gated, never silently omitted.\n- Reserved filters (`year`, `trim`) fail loudly with `unsupported_filter` rather than\n pretending to filter.\n\nThe dataset's own measured error rates are published too, with their confidence\nintervals: [QUALITY.md](https://github.com/vehiclesdb/vehiclesdb/blob/main/QUALITY.md).\n\n## The official Ruby client\n\nThe [`vehicles` gem](https://github.com/vehiclesdb/vehicles) wraps this API:\nconfigure `api_key` and `Vehicles.find(\"vw golf\").image(color: \"red\")` answers with a\nvariant URL — degrading to `nil`, never raising, when imagery is absent. The\n[open dataset](https://github.com/vehiclesdb/vehiclesdb) is free to download and\nalways will be; this API is the hosted, resolved, enriched version of it.\n", "termsOfService": "https://vehiclesdb.com/legal/api-terms", "contact": { "name": "VehiclesDB support", "url": "https://vehiclesdb.com/api", "email": "support@vehiclesdb.com" }, "license": { "name": "Identity layer CC-BY-4.0; enrichment and resolution proprietary", "url": "https://vehiclesdb.com/legal/attribution" } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "API key authentication. Mint keys at [vehiclesdb.com/settings/api-keys](https://vehiclesdb.com/settings/api-keys) and send them as a Bearer token: `Authorization: Bearer vdb_sk_your_key`. There are two kinds. Your private key (`vdb_sk_`) is like a password: it lives on your server, works everywhere, and spends credits. Your public key (also called a publishable key, `vdb_pk_`) is safe to put in a website where anyone can see it: it only opens the free Dropdown Data endpoints and spends nothing. Never put a private key in a browser — the variant URLs the API returns are signed precisely so you never have to." } }, "schemas": { "OriginNotAllowed": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "origin": { "type": [ "string", "null" ], "description": "The host this request came from, read from its Origin header, or Referer when Origin is absent; null when it sent neither. Never the key's allowed websites." } }, "required": [ "error", "message", "origin" ] }, "ModelList": { "type": "object", "properties": { "make": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "name", "slug" ] }, "models": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "kind": { "type": "string" }, "body_type": { "type": [ "string", "null" ] }, "popularity_decile": { "type": [ "integer", "null" ] }, "years_on_record": { "type": [ "object", "null" ], "properties": { "first": { "type": "integer" }, "last": { "type": "integer" } }, "required": [ "first", "last" ], "description": "The first and last year the official registers have the model on record; null when none. Register years, not production or model years." } }, "required": [ "name", "slug", "kind", "body_type", "popularity_decile", "years_on_record" ] } }, "count": { "type": "integer" }, "dataset_version": { "type": "string" }, "attribution": { "type": "object", "properties": { "source": { "type": "string" }, "url": { "type": "string" }, "license": { "type": "string" }, "dataset_version": { "type": "string" } }, "required": [ "source", "url", "license", "dataset_version" ] } }, "required": [ "make", "models", "count", "dataset_version", "attribution" ] }, "FullRecord": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "make": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "kind": { "type": "string" }, "body_type": { "type": [ "string", "null" ] }, "availability": { "type": "array", "items": { "type": "string" } }, "regions": { "type": "array", "items": { "type": "string" } }, "popularity": { "type": "object", "properties": { "global_decile": { "type": [ "integer", "null" ] }, "mass_decile": { "type": [ "integer", "null" ] }, "rarity": { "type": [ "string", "null" ] } }, "required": [ "global_decile", "mass_decile", "rarity" ] }, "aliases": { "type": "array", "items": { "type": "string" } }, "former_ids": { "type": "array", "items": { "type": "string" } }, "years": { "type": [ "object", "null" ] }, "era": { "type": [ "string", "null" ], "enum": [ "vintage", "classic", "discontinued", null ] }, "enrichment": { "type": [ "object", "null" ], "properties": { "production_runs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The row's stable id, derived from its content (a change to the fact changes it). What a `provenance` row's `ref` names." }, "year_start": { "type": "integer" }, "year_end": { "type": "integer", "description": "The last year. Absent when the end is unknown or the row is still open." }, "ended": { "type": "boolean", "enum": [ true ], "description": "Present (true) when the row is positively over but its last year is not yet sourced." }, "year_end_min": { "type": "integer", "description": "A floor, never an end year: built until at least this year. Only with `ended`." }, "note": { "type": "string" } }, "required": [ "id", "year_start" ] } }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The row's stable id, derived from its content (a change to the fact changes it). What a `provenance` row's `ref` names." }, "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "name", "type" ] } }, "links": { "type": "object", "additionalProperties": { "type": "string" } }, "relations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": [ "string", "null" ], "description": "The related vehicle's canonical id; null when the catalog has no record for it." }, "name": { "type": "string" }, "row_id": { "type": "string", "description": "The relation row's own stable id, what a `provenance` row's `ref` names (`id` is the related vehicle's)." } }, "required": [ "type", "id", "name", "row_id" ] } }, "powertrains": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string" }, "basis": { "type": "string" }, "basis_note": { "type": "string" }, "counts": { "type": "object", "additionalProperties": { "type": "integer" } } }, "required": [ "country", "basis", "basis_note", "counts" ] } }, "make_facts": { "type": [ "object", "null" ], "properties": { "founded": { "type": "integer" }, "dissolved": { "type": [ "integer", "null" ] }, "country": { "type": "string" }, "parent": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "note": { "type": "string" } } }, "generations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The row's stable id, derived from its content (a change to the fact changes it). What a `provenance` row's `ref` names." }, "name": { "type": "string" }, "codes": { "type": "array", "items": { "type": "string" } }, "year_start": { "type": "integer" }, "year_end": { "type": "integer", "description": "The last year. Absent when the end is unknown or the row is still open." }, "ended": { "type": "boolean", "enum": [ true ], "description": "Present (true) when the row is positively over but its last year is not yet sourced." }, "year_end_min": { "type": "integer", "description": "A floor, never an end year: built until at least this year. Only with `ended`." }, "derived": { "type": "boolean", "description": "true: promoted from a `type: generation` variant by the pipeline's rule rather than curated by hand." }, "from_variant": { "type": "integer", "description": "With `derived`: the index into `variants` of the row it came from." } }, "required": [ "id", "name", "year_start" ] } }, "provenance": { "type": "array", "items": { "$ref": "#/components/schemas/Citation" } }, "make_provenance": { "type": "array", "items": { "$ref": "#/components/schemas/Citation" } } }, "required": [ "production_runs", "variants", "links", "relations", "powertrains", "make_facts", "generations", "provenance", "make_provenance" ], "description": "null, with `enrichment_gated: true`, when your plan does not include it." }, "enrichment_gated": { "type": "boolean" }, "upgrade_url": { "type": "string", "description": "Only when `enrichment_gated`." }, "dataset_version": { "type": "string" }, "attribution": { "type": "object", "properties": { "source": { "type": "string" }, "url": { "type": "string" }, "license": { "type": "string" }, "dataset_version": { "type": "string" } }, "required": [ "source", "url", "license", "dataset_version" ] } }, "required": [ "id", "name", "make", "kind", "body_type", "availability", "regions", "popularity", "aliases", "former_ids", "years", "era", "enrichment", "enrichment_gated", "dataset_version", "attribution" ] }, "Citation": { "type": "object", "properties": { "field": { "type": [ "string", "null" ], "description": "The field the source is for: `production_runs`, `variants`, `relations`, `generations`, `links` or `note` on a record; `founded`, `dissolved`, `country`, `parent`, `website` or `note` on a make. null when it is for the record or make as a whole." }, "item": { "type": [ "integer", "string", "null" ], "description": "The positional form of the same join: the index into that field's array, the link's name for `links`, null for a citation on a whole field. Prefer `ref`, which survives re-ordering." }, "ref": { "type": [ "string", "null" ], "description": "The `id` of the exact row this cites (`relations[].row_id` for a relation). null for a field-level, entry-level, link, note or make citation." }, "url": { "type": [ "string", "null" ], "description": "null only for evidence held in the data itself (see `in_data`)." }, "accessed": { "type": [ "string", "null" ], "format": "date", "description": "When the curator read the source; null when no access date was recorded." }, "field_tier": { "type": "string", "enum": [ "primary-manufacturer", "primary-register", "primary-instrument", "secondary-wikipedia", "secondary-press", "secondary-reference", "corroboration-only", "observed-in-corpus" ], "description": "The curator's evidence tier for the whole field, copied onto each of its rows. ABSENT means cited, tier unknown: there is a source to check, nobody graded it." }, "tier": { "type": "string", "enum": [ "secondary-wikipedia" ], "description": "Inferred from the URL's host (a wikipedia.org page), never curated." }, "tier_inferred": { "type": "boolean", "enum": [ true ], "description": "Always beside `tier`." }, "inherited": { "type": "boolean", "enum": [ true ], "description": "Copied from the item above by a \"same page\" note of the curator." }, "in_data": { "type": "string", "description": "The evidence string when the source is our own register data rather than a URL." } }, "required": [ "field", "item", "ref", "url", "accessed" ] }, "d42512f8fa40041d675113e3ee389ef7": { "type": "object", "properties": { "input": { "type": "string" }, "kind_hint": { "type": "string" }, "country_hint": { "type": "string" }, "private": { "type": "boolean" } }, "required": [ "input" ] }, "7a43100abf9fa8a1bf09c08cb60e2b58": { "type": "object", "properties": { "match": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "make": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "kind": { "type": "string" }, "confidence": { "type": "number" }, "method": { "type": "string" } }, "required": [ "id", "name", "make", "kind", "confidence", "method" ] }, "alternates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" }, "confidence": { "type": "number" } }, "required": [ "id", "name", "kind", "confidence" ] } }, "resolved_via": { "type": "array", "items": { "type": "string" } }, "dataset_version": { "type": "string" }, "attribution": { "type": "object", "properties": { "source": { "type": "string" }, "url": { "type": "string" }, "license": { "type": "string" }, "dataset_version": { "type": "string" } }, "required": [ "source", "url", "license", "dataset_version" ] } }, "required": [ "alternates", "resolved_via", "dataset_version", "attribution" ] }, "af967196b4de0bf714eaf777b8aba8e5": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "e05c40bd0bef62708ee07de41ba7bb34": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] }, "d830223a507fcd0b65c51ef814cb376e": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "balance": { "type": "integer" }, "packs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "credits": { "type": "integer" }, "price": { "type": "string" } }, "required": [ "name", "credits", "price" ] } }, "billing_url": { "type": "string" } }, "required": [ "error", "message", "packs", "billing_url" ] }, "d37714d66fd4b61b39fbb81b529949d0": { "type": "object", "properties": { "key": { "type": "object", "properties": { "name": { "type": "string" }, "prefix": { "type": "string" }, "last4": { "type": "string" }, "masked": { "type": "string" }, "created_at": { "type": "string" }, "last_used_at": { "type": "string" }, "expires_at": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } } }, "required": [ "prefix", "last4", "masked", "created_at", "scopes" ] }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "plan": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" } }, "required": [ "key", "name" ] }, "credits": { "type": "object", "properties": { "remaining": { "type": "integer" }, "cost_of_this_request": { "type": "integer" } }, "required": [ "remaining", "cost_of_this_request" ] }, "dataset_version": { "type": "string" }, "attribution": { "type": "object", "properties": { "source": { "type": "string" }, "url": { "type": "string" }, "license": { "type": "string" }, "dataset_version": { "type": "string" } }, "required": [ "source", "url", "license", "dataset_version" ] } }, "required": [ "key", "organization", "plan", "credits", "dataset_version", "attribution" ] }, "d665dd9ad553cb337a5ef4c3ac174335": { "type": "object", "properties": { "id": { "type": "string" }, "color": { "type": "string" }, "requested_color": { "type": "string" }, "palette": { "type": "array", "items": { "type": "string" } }, "variants": { "type": "object", "properties": { "sm": { "type": "object", "properties": { "url": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" } }, "required": [ "url", "width", "height" ] }, "md": { "type": "object", "properties": { "url": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" } }, "required": [ "url", "width", "height" ] }, "lg": { "type": "object", "properties": { "url": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" } }, "required": [ "url", "width", "height" ] } }, "required": [ "sm", "md", "lg" ] }, "format": { "type": "string" }, "provenance": { "type": "object", "properties": { "generated": { "type": "boolean" }, "license_note": { "type": "string" } }, "required": [ "generated", "license_note" ] }, "attribution": { "type": "object", "properties": { "source": { "type": "string" }, "url": { "type": "string" }, "license": { "type": "string" }, "dataset_version": { "type": "string" } }, "required": [ "source", "url", "license", "dataset_version" ] } }, "required": [ "id", "color", "requested_color", "palette", "variants", "format", "provenance", "attribution" ] }, "2adc412d9e4371f25d519d4f6755fe51": { "type": "object", "properties": { "error": { "type": "string" }, "id": { "type": "string" } }, "required": [ "error", "id" ] }, "516fc6579452876318417a0c407630a6": { "type": "object", "properties": { "jurisdiction": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "country": { "type": "string" }, "authority": { "type": "string" }, "series_count": { "type": "integer" } }, "required": [ "code", "name", "country", "series_count" ] }, "series": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "class": { "type": "string" }, "pattern": { "type": "string" }, "period": { "type": "object", "properties": { "start": { "type": "integer" }, "end": { "type": "integer" } } }, "categories": { "type": "array", "items": { "type": "string" } }, "background": { "type": "string" }, "foreground": { "type": "string" }, "render_url": { "type": "string" } }, "required": [ "id", "class", "pattern", "categories", "render_url" ] } }, "attribution": { "type": "object", "properties": { "source": { "type": "string" }, "url": { "type": "string" }, "license": { "type": "string" }, "dataset_version": { "type": "string" } }, "required": [ "source", "url", "license", "dataset_version" ] } }, "required": [ "jurisdiction", "series", "attribution" ] }, "7088c7434207a64ad5bf0b696bed6ca0": { "type": "object", "properties": { "plate": { "type": "string" }, "jurisdiction": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "country": { "type": "string" }, "authority": { "type": "string" }, "series_count": { "type": "integer" } }, "required": [ "code", "name", "country", "series_count" ] }, "valid": { "type": "boolean" }, "exact": { "type": "boolean" }, "as_issued": { "type": "string" }, "matches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "class": { "type": "string" }, "pattern": { "type": "string" }, "period": { "type": "object", "properties": { "start": { "type": "integer" }, "end": { "type": "integer" } } }, "categories": { "type": "array", "items": { "type": "string" } }, "background": { "type": "string" }, "foreground": { "type": "string" }, "render_url": { "type": "string" } }, "required": [ "id", "class", "pattern", "categories", "render_url" ] } }, "attribution": { "type": "object", "properties": { "source": { "type": "string" }, "url": { "type": "string" }, "license": { "type": "string" }, "dataset_version": { "type": "string" } }, "required": [ "source", "url", "license", "dataset_version" ] } }, "required": [ "plate", "jurisdiction", "valid", "exact", "matches", "attribution" ] }, "0b3f8486151097dc770d102f0a4eaa5e": { "type": "object", "properties": { "makes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "kinds": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "slug", "kinds" ] } }, "count": { "type": "integer" }, "dataset_version": { "type": "string" }, "attribution": { "type": "object", "properties": { "source": { "type": "string" }, "url": { "type": "string" }, "license": { "type": "string" }, "dataset_version": { "type": "string" } }, "required": [ "source", "url", "license", "dataset_version" ] } }, "required": [ "makes", "count", "dataset_version", "attribution" ] }, "7817692ee5a2caa62b9c95873d526f2b": { "type": "object", "properties": { "make": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "kinds": { "type": "array", "items": { "type": "string" } }, "model_count": { "type": "integer" }, "popularity_rank": { "type": "integer" }, "models_url": { "type": "string" }, "logo_url": { "type": "string" } }, "required": [ "name", "slug", "kinds", "model_count", "models_url" ] }, "dataset_version": { "type": "string" }, "attribution": { "type": "object", "properties": { "source": { "type": "string" }, "url": { "type": "string" }, "license": { "type": "string" }, "dataset_version": { "type": "string" } }, "required": [ "source", "url", "license", "dataset_version" ] } }, "required": [ "make", "dataset_version", "attribution" ] }, "ec0ebc08fa1c19ac03699418fac05c62": { "type": "string" }, "7b4e331ae7b0830158b4463964349fc8": { "type": "object", "properties": { "query": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "kind": { "type": "string" }, "make": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "name", "slug" ] }, "body_type": { "type": "string" }, "popularity_decile": { "type": "integer" } }, "required": [ "name", "slug", "kind", "make" ] } }, "count": { "type": "integer" }, "corrected_query": { "type": "string" }, "dataset_version": { "type": "string" }, "attribution": { "type": "object", "properties": { "source": { "type": "string" }, "url": { "type": "string" }, "license": { "type": "string" }, "dataset_version": { "type": "string" } }, "required": [ "source", "url", "license", "dataset_version" ] } }, "required": [ "query", "results", "count", "dataset_version", "attribution" ] }, "ac198a14140f7771f6505f73f58576e7": { "type": "object", "properties": { "makes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "kinds": { "type": "array", "items": { "type": "string" } }, "models": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "kind": { "type": "string" }, "body_type": { "type": "string" }, "popularity_decile": { "type": "integer" } }, "required": [ "name", "slug", "kind" ] } } }, "required": [ "name", "slug", "kinds", "models" ] } }, "count": { "type": "integer" }, "model_count": { "type": "integer" }, "dataset_version": { "type": "string" }, "attribution": { "type": "object", "properties": { "source": { "type": "string" }, "url": { "type": "string" }, "license": { "type": "string" }, "dataset_version": { "type": "string" } }, "required": [ "source", "url", "license", "dataset_version" ] } }, "required": [ "makes", "count", "model_count", "dataset_version", "attribution" ] } }, "responses": { "f71d55f4a8d031af994a00bcc4aacdb3": { "description": "Resolution result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/7a43100abf9fa8a1bf09c08cb60e2b58" }, "examples": { "resolved_via_make_alias": { "$ref": "#/components/examples/3ad289c5569c01d517e61a5c465643b5" }, "registry_row,_kind_collision_narrowed": { "$ref": "#/components/examples/5d1b6017c3dce0957bb0d24d116c0e2b" }, "misspelled_make": { "$ref": "#/components/examples/8513b6f13f5d83d843d9e084f87f9424" }, "honestly_unresolved,_a_name_without_a_make": { "$ref": "#/components/examples/9920ca46a01e22afe863ae83f9a1807c" } } } } }, "5e0b490756ac5ced147b298cf34b8d34": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/af967196b4de0bf714eaf777b8aba8e5" }, "examples": { "missing_or_invalid_api_key": { "$ref": "#/components/examples/8db9435f87099225e9223de878892143" } } } } }, "42cb92148ba6af17e566a475c0d4c61a": { "description": "This endpoint needs your private key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/e05c40bd0bef62708ee07de41ba7bb34" }, "examples": { "public_key_refused": { "$ref": "#/components/examples/b3c98ff69fd9bfadbd54955cea579cff" } } } } }, "696d51887e34eea508345e4531b2c8fc": { "description": "Out of credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/d830223a507fcd0b65c51ef814cb376e" }, "examples": { "out_of_credits": { "$ref": "#/components/examples/a8b24f63b609b2d0e17329d2c27c9738" } } } } }, "81e4083ad712327fc36264a24317d334": { "description": "Invalid input or hint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/af967196b4de0bf714eaf777b8aba8e5" }, "examples": { "blank_input": { "$ref": "#/components/examples/005fdcfb3f7747aded2ef2f59e39f1b0" }, "unknown_kind_hint": { "$ref": "#/components/examples/6fe37725bbb67bece9322d6671c4fae0" } } } } }, "039f5e9a1470229b189a4118a03484d2": { "description": "Key identity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/d37714d66fd4b61b39fbb81b529949d0" }, "examples": { "a_live_key_on_the_free_plan": { "$ref": "#/components/examples/00e77d639dfba7727b2853c511693f88" } } } } }, "0f594d7485ff2eebc74c835a7a586d2e": { "description": "Missing, revoked or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/af967196b4de0bf714eaf777b8aba8e5" }, "examples": { "missing_or_invalid_api_key": { "$ref": "#/components/examples/8db9435f87099225e9223de878892143" } } } } }, "9d8630a30ca9d5271f753a28f54289f7": { "description": "Full record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FullRecord" }, "examples": { "generations_and_sources_(developer_plan)": { "$ref": "#/components/examples/a104d83aee0be07f0d61c31e6aa43029" }, "free_plan_(enrichment_gated)": { "$ref": "#/components/examples/fb974ffa7e48679431af83bf11ef92ed" } } } } }, "b8d681f089b6b5ccb511487c7ac6350b": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/af967196b4de0bf714eaf777b8aba8e5" }, "examples": { "unknown_id": { "$ref": "#/components/examples/652b4dc0535c89b96819b6ec3e4acc96" } } } } }, "4fe5bf3223c0a287d63b1793cad4b81b": { "description": "Vehicle imagery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/d665dd9ad553cb337a5ef4c3ac174335" }, "examples": { "requested_color_is_rendered": { "$ref": "#/components/examples/5885ca56f3ae3832187c699a2274d4c1" }, "un-rendered_color_falls_back_honestly": { "$ref": "#/components/examples/42c2416f9ba6841f87de9a72d6b07198" } } } } }, "f28e861f856a1931bf99aedb6e6f8a5d": { "description": "No imagery for this vehicle yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/2adc412d9e4371f25d519d4f6755fe51" }, "examples": { "no_imagery_for_this_vehicle_yet": { "$ref": "#/components/examples/2d065b51a2d050f0b2214e8edd1e4df3" } } } } }, "4253077089ffb25b30ce120c4f191c54": { "description": "Unknown color or reserved filter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/af967196b4de0bf714eaf777b8aba8e5" }, "examples": { "color_outside_the_canonical_palette": { "$ref": "#/components/examples/6c70e3924e1f19f2b0b6a2935f598fab" }, "reserved_filter_used": { "$ref": "#/components/examples/ca75e032e55451e47b0adee79983834e" } } } } }, "3c29ac8ebdc307939f076d8cade0cda2": { "description": "The jurisdiction and its series", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/516fc6579452876318417a0c407630a6" }, "examples": { "germany_with_the_series_list_abridged_to_2_of_13": { "$ref": "#/components/examples/ec6bd8e5577a73c328211f49a40150c7" } } } } }, "7db1fa052774f7fe62f612a9f5d1b72d": { "description": "Unknown jurisdiction code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/af967196b4de0bf714eaf777b8aba8e5" }, "examples": { "unknown_jurisdiction_code": { "$ref": "#/components/examples/f1743063fbe64a04ba560a5d324aa768" } } } } }, "7e7bddcf7a2179819956bb1b7200f4a6": { "description": "The match verdict and every matching series", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/7088c7434207a64ad5bf0b696bed6ca0" }, "examples": { "exact_match_so_as_issued_is_null": { "$ref": "#/components/examples/a502fbc1da8c56fe40fcea35d55a21e2" }, "lenient_match_with_separators_forgiven": { "$ref": "#/components/examples/6daccbbabe8cb64f20a92c01f850f9ef" } } } } }, "54620957a0a3fde27fc1b610f98112fd": { "description": "Missing plate parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/e05c40bd0bef62708ee07de41ba7bb34" }, "examples": { "missing_plate_parameter": { "$ref": "#/components/examples/d26a7f00336ab88ce1228aad823b80cf" } } } } }, "dda7003d85106722b22d59fdaf07b651": { "description": "The make list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/0b3f8486151097dc770d102f0a4eaa5e" }, "examples": { "cars_sold_in_germany": { "$ref": "#/components/examples/2bcdcd7c08284179fb10c9889da18022" } } } } }, "04da906e873ef5bdcffbaffb418b6804": { "description": "Unknown kind or country", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/e05c40bd0bef62708ee07de41ba7bb34" }, "examples": { "unknown_kind": { "$ref": "#/components/examples/37a4717e9bcbd37e11eb01dbf236149d" } } } } }, "85fd2a698fdc496f66f981f3d398ff61": { "description": "Origin not allowed for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OriginNotAllowed" }, "examples": { "origin_not_allowed": { "$ref": "#/components/examples/dd64d33cda20d996e43e036773e3abf0" } } } } }, "c9e6aab96740c77c464fbbc7b00a20fd": { "description": "The make", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/7817692ee5a2caa62b9c95873d526f2b" }, "examples": { "audi": { "$ref": "#/components/examples/70df45c095a20d89d08f67710ad30f94" } } } } }, "6b23d7ae15e1dc648a848579ad6a3076": { "description": "Unknown make", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/af967196b4de0bf714eaf777b8aba8e5" }, "examples": { "unknown_make": { "$ref": "#/components/examples/b5f69419e51e76c08c3c0402a13ec397" } } } } }, "03277160af6e4225c41cc4c1c5ea3dd5": { "description": "The model list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelList" }, "examples": { "audi's_models,_most_popular_first": { "$ref": "#/components/examples/e398301f316725a8722c441a72c35449" } } } } }, "ed37dfa1449f133386ef76710e50df5e": { "description": "Unknown kind or country", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/e05c40bd0bef62708ee07de41ba7bb34" }, "examples": { "unknown_country": { "$ref": "#/components/examples/8be1b3f2363ff979ce0b3011396ff5e6" } } } } }, "f0ae0cbd151a7e3ae42c299dbb079603": { "description": "The logo file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ec0ebc08fa1c19ac03699418fac05c62" } } } }, "43d4678d59af17c7cd363c5d94d6b8e4": { "description": "No logo for this make", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/e05c40bd0bef62708ee07de41ba7bb34" }, "examples": { "no_logo_for_this_make": { "$ref": "#/components/examples/cc715cb2365b25fab05e4f466feb2085" } } } } }, "32ad41e02ec6088939c28e37c340b7f0": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/7b4e331ae7b0830158b4463964349fc8" }, "examples": { "searching_for_the_golf": { "$ref": "#/components/examples/001cabc7906748e72c2688fd79d8f9fe" }, "a_misspelled_make,_corrected": { "$ref": "#/components/examples/442b17797b18fc06a63cf24664537395" } } } } }, "a55bb0e8be1152a513b5ae79aa7efdac": { "description": "Missing query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/e05c40bd0bef62708ee07de41ba7bb34" }, "examples": { "missing_query": { "$ref": "#/components/examples/c646358c4f318202e18a1b6db3e88146" } } } } }, "9aa8146ffd22f73631f928f59ecdbacd": { "description": "The catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ac198a14140f7771f6505f73f58576e7" }, "examples": { "one_make_of_the_tree": { "$ref": "#/components/examples/8cf4d0020748753eb481337a61b8844c" } } } } }, "7ba5ea796b1ca2aa817851cf275ff5a4": { "description": "Unknown kind", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/e05c40bd0bef62708ee07de41ba7bb34" }, "examples": { "unknown_kind": { "$ref": "#/components/examples/37a4717e9bcbd37e11eb01dbf236149d" } } } } } }, "parameters": { "770a251473e34d3bfea73ec9a34c74c3": { "name": "kind", "in": "path", "description": "Vehicle kind: `car`, `motorcycle`, `moped`, `van`, `truck` or `bus`", "required": true, "schema": { "type": "string" }, "style": "simple" }, "d8229c95093aac91811f8d163a1671c6": { "name": "make_slug", "in": "path", "description": "Canonical make slug (e.g. `renault`, `mercedes-benz`)", "required": true, "schema": { "type": "string" }, "style": "simple" }, "model_slug": { "name": "model_slug", "in": "path", "description": "Canonical model slug (e.g. `clio`, `yaris-cross`)", "required": true, "schema": { "type": "string" }, "style": "simple" }, "color": { "name": "color", "in": "query", "description": "Palette color slug to render (default `grey`). Un-rendered colors fall back honestly — check `color` vs `requested_color` in the response.", "required": false, "schema": { "type": "string" }, "style": "form" }, "format": { "name": "format", "in": "query", "description": "Variant format: `webp` (default) or `png`", "required": false, "schema": { "type": "string" }, "style": "form" }, "code": { "name": "code", "in": "path", "description": "Jurisdiction code — a country (`de`) or a subdivision (`us-ca`).", "required": true, "schema": { "type": "string" }, "style": "simple" }, "plate": { "name": "plate", "in": "query", "description": "The registration to test — spaces, hyphens and dots are all accepted.", "required": true, "schema": { "type": "string" }, "style": "form" }, "f39a4d8163a03f106350daaf553226e7": { "name": "kind", "in": "query", "description": "Only makes with at least one model of this kind. One of: `car`, `motorcycle`, `moped`, `van`, `truck`, `bus`.", "required": false, "schema": { "type": "string" }, "style": "form" }, "949c84f59976298e825dbe124b677463": { "name": "country", "in": "query", "description": "Only makes with register evidence in this country (two-letter code, one of the 18 source countries, e.g. `de`, `us`, `gb`).", "required": false, "schema": { "type": "string" }, "style": "form" }, "c4081d506332efcb661ee0bc8698d48e": { "name": "order", "in": "query", "description": "`popular` ranks makes by real-world registrations (Honda and Mercedes first, one-model historics last); anything else (or nothing) is alphabetical.", "required": false, "schema": { "type": "string" }, "style": "form" }, "c64c3dd7609b9e962e79cf1969dd374b": { "name": "limit", "in": "query", "description": "Cap the list, e.g. `order=popular&limit=40` for a top-brands dropdown. Default: everything.", "required": false, "schema": { "type": "integer" }, "style": "form" }, "213bd67811aeb10510c88a2dbb4bdbed": { "name": "make_slug", "in": "path", "description": "The make's slug from the make list, e.g. `audi`.", "required": true, "schema": { "type": "string" }, "style": "simple" }, "eb436a0dd2958df386b3d676bf02ac52": { "name": "kind", "in": "query", "description": "Only models of this kind (an Iveco 35 is both a `van` and a `truck`). One of: `car`, `motorcycle`, `moped`, `van`, `truck`, `bus`.", "required": false, "schema": { "type": "string" }, "style": "form" }, "126579f3d7114c0ab098cb9f315f0128": { "name": "country", "in": "query", "description": "Only models with register evidence in this country (two-letter code, e.g. `de`).", "required": false, "schema": { "type": "string" }, "style": "form" }, "d2b4651ba8d60af148d0d3ea300b56f7": { "name": "order", "in": "query", "description": "`popular` sorts most-registered first: by the `country`'s own registration rank when you pass one and the dataset has it, then by registration decile; anything else (or nothing) is alphabetical.", "required": false, "schema": { "type": "string" }, "style": "form" }, "variant": { "name": "variant", "in": "query", "description": "`emblem` prefers the badge alone; anything else (or nothing) prefers the fuller logo treatment.", "required": false, "schema": { "type": "string" }, "style": "form" }, "q": { "name": "q", "in": "query", "description": "What the person typed, e.g. `golf` or `vw gol`.", "required": true, "schema": { "type": "string" }, "style": "form" }, "61fa9560b7bd4d56c49fb058c2d7234c": { "name": "limit", "in": "query", "description": "Results to return, 1–25. Default 10.", "required": false, "schema": { "type": "integer" }, "style": "form" }, "9839b2e79ab2f918f8c5295b0beb84ae": { "name": "kind", "in": "query", "description": "Only makes and models of this kind. One of: `car`, `motorcycle`, `moped`, `van`, `truck`, `bus`.", "required": false, "schema": { "type": "string" }, "style": "form" } }, "requestBodies": { "92252243ccdb43db1df9f5a01e39fa7d": { "description": "The string to resolve, with optional hints", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/d42512f8fa40041d675113e3ee389ef7" }, "examples": { "registry_row": { "$ref": "#/components/examples/7e4802ada3501d68555cd22242387987" }, "marketplace_title": { "$ref": "#/components/examples/149130d2e0c147ac2b164d3fe2cf38a0" } } } }, "required": true } }, "headers": {}, "examples": { "7e4802ada3501d68555cd22242387987": { "summary": "Registry row", "value": { "input": "MERCEDES-BENZ | SPRINTER", "kind_hint": "van", "country_hint": "de" } }, "149130d2e0c147ac2b164d3fe2cf38a0": { "summary": "Marketplace title", "value": { "input": "VW Golf" } }, "3ad289c5569c01d517e61a5c465643b5": { "summary": "Resolved via make alias", "value": { "match": { "id": "car/volkswagen/golf", "name": "Golf", "make": { "id": "volkswagen", "name": "Volkswagen" }, "kind": "car", "confidence": 0.97, "method": "alias" }, "alternates": [], "resolved_via": [ "make_alias:vw→volkswagen", "fold:golf→golf" ], "dataset_version": "2026.10.3", "attribution": { "source": "VehiclesDB", "url": "https://vehiclesdb.com", "license": "Identity layer: CC-BY-4.0; enrichment/resolution: proprietary. Display requires visible credit — see https://vehiclesdb.com/legal/attribution", "dataset_version": "2026.10.3" } } }, "5d1b6017c3dce0957bb0d24d116c0e2b": { "summary": "Registry row, kind collision narrowed", "value": { "match": { "id": "van/mercedes-benz/sprinter", "name": "Sprinter", "make": { "id": "mercedes-benz", "name": "Mercedes-Benz" }, "kind": "van", "confidence": 0.97, "method": "fold" }, "alternates": [ { "id": "bus/mercedes-benz/sprinter", "name": "Sprinter", "kind": "bus", "confidence": 0.45 }, { "id": "truck/mercedes-benz/sprinter", "name": "Sprinter", "kind": "truck", "confidence": 0.45 } ], "resolved_via": [ "fold:sprinter→sprinter", "kind_hint:van" ], "dataset_version": "2026.10.3", "attribution": { "source": "VehiclesDB", "url": "https://vehiclesdb.com", "license": "Identity layer: CC-BY-4.0; enrichment/resolution: proprietary. Display requires visible credit — see https://vehiclesdb.com/legal/attribution", "dataset_version": "2026.10.3" } } }, "8513b6f13f5d83d843d9e084f87f9424": { "summary": "Misspelled make", "value": { "match": { "id": "car/mercedes-benz/gla", "name": "GLA", "make": { "id": "mercedes-benz", "name": "Mercedes-Benz" }, "kind": "car", "confidence": 0.8, "method": "fuzzy" }, "alternates": [], "resolved_via": [ "make_typo:marcedes→mercedes-benz", "fold:gla→gla" ], "dataset_version": "2026.10.3", "attribution": { "source": "VehiclesDB", "url": "https://vehiclesdb.com", "license": "Identity layer: CC-BY-4.0; enrichment/resolution: proprietary. Display requires visible credit — see https://vehiclesdb.com/legal/attribution", "dataset_version": "2026.10.3" } } }, "9920ca46a01e22afe863ae83f9a1807c": { "summary": "Honestly unresolved, a name without a make", "value": { "match": null, "alternates": [ { "id": "car/volkswagen/golf", "name": "Golf", "kind": "car", "confidence": 0.2 }, { "id": "car/volkswagen/e-golf", "name": "E-Golf", "kind": "car", "confidence": 0.2 }, { "id": "moped/monobuggy/evoking-golf", "name": "Evoking Golf", "kind": "moped", "confidence": 0.2 } ], "resolved_via": [], "dataset_version": "2026.10.3", "attribution": { "source": "VehiclesDB", "url": "https://vehiclesdb.com", "license": "Identity layer: CC-BY-4.0; enrichment/resolution: proprietary. Display requires visible credit — see https://vehiclesdb.com/legal/attribution", "dataset_version": "2026.10.3" } } }, "8db9435f87099225e9223de878892143": { "summary": "Missing or invalid API key", "value": { "error": "unauthorized" } }, "b3c98ff69fd9bfadbd54955cea579cff": { "summary": "Public key refused", "value": { "error": "publishable_key_not_allowed", "message": "Public keys (vdb_pk_) only work on the free dropdown endpoints: makes, models, search, logos and the whole catalog. This endpoint needs your private key, the one that stays on your server and spends credits. Mint one at https://vehiclesdb.com/settings/api-keys and send it from your backend, never from a browser." } }, "a8b24f63b609b2d0e17329d2c27c9738": { "summary": "Out of credits", "value": { "error": "insufficient_credits", "message": "Your organization is out of API credits…", "balance": 0, "packs": [ { "name": "boost", "credits": 10000, "price": "19.00 USD" } ], "billing_url": "https://vehiclesdb.com/billing" } }, "005fdcfb3f7747aded2ef2f59e39f1b0": { "summary": "Blank input", "value": { "error": "blank_input" } }, "6fe37725bbb67bece9322d6671c4fae0": { "summary": "Unknown kind_hint", "value": { "error": "unknown_kind_hint", "kinds": [ "car", "motorcycle", "moped", "van", "truck", "bus" ] } }, "00e77d639dfba7727b2853c511693f88": { "summary": "A live key on the free plan", "value": { "key": { "name": "my-app", "prefix": "vdb_", "last4": "9f3c", "masked": "vdb_••••9f3c", "created_at": "2026-08-24T10:15:00Z", "last_used_at": null, "expires_at": null, "scopes": [] }, "organization": { "id": "8b1f…", "name": "Acme" }, "plan": { "key": "free", "name": "Free" }, "credits": { "remaining": 1000, "cost_of_this_request": 0 }, "dataset_version": "2026.10.3", "attribution": { "source": "VehiclesDB", "url": "https://vehiclesdb.com", "license": "Identity layer: CC-BY-4.0; enrichment/resolution: proprietary. Display requires visible credit — see https://vehiclesdb.com/legal/attribution", "dataset_version": "2026.10.3" } } }, "a104d83aee0be07f0d61c31e6aa43029": { "summary": "Generations and sources (Developer plan)", "value": { "id": "car/nissan/350", "name": "350", "make": { "id": "nissan", "name": "Nissan" }, "kind": "car", "body_type": "hatchback", "availability": [ "gb" ], "regions": [ "eu" ], "popularity": { "global_decile": 3, "mass_decile": 2, "rarity": "common" }, "aliases": [], "former_ids": [], "years": null, "era": "discontinued", "enrichment": { "production_runs": [ { "id": "run-2002-2008", "year_start": 2002, "year_end": 2008, "note": "Z33 PRODUCTION SPAN, the fifth-generation Z-car (Fairlady Z in Japan, 350Z overseas): on sale from July 2002 and continued until December 2008. The UK register carries the car under the model string 350Z, so this id is the British 350Z;" } ], "variants": [ { "id": "generation-z33-fifth-generation-z-350z-fairlady-z", "name": "Z33 (fifth-generation Z, 350Z / Fairlady Z)", "type": "generation" }, { "id": "body-roadster", "name": "Roadster", "type": "body" }, { "id": "engine-3-5-vq35de-v6", "name": "3.5 VQ35DE V6", "type": "engine" } ], "links": { "maker_heritage_z33": "https://www.nissan-global.com/EN/HERITAGE_COLLECTION/284_fairlady_z_version_st.html", "maker_heritage_roadster": "https://www.nissan-global.com/EN/HERITAGE_COLLECTION/383_fairlady_z_roadster.html", "maker_japan_launch": "https://global.nissannews.com/en/releases/release-2a0702e6a87ace39439e9e572af5d370-020730-01", "maker_model_names_table": "https://www.nissan-global.com/PDF/ff_fy01e15.pdf" }, "relations": [ { "type": "market_name_of", "id": "car/nissan/fairlady-z", "name": "Nissan Fairlady Z", "row_id": "market-name-of-car-nissan-fairlady-z" } ], "powertrains": [], "make_facts": { "founded": 1933, "country": "JP", "website": "https://www.nissan-global.com", "note": "COMPANY OUTLINE, read off Nissan's own page, which is stated 'As of March 31, 2026': company name Nissan Motor Co., Ltd.; established 26 December 1933; registered head office at 2, Takara-cho, Kanagawa-ku, Yokohama, Kanagawa 220-8623, Japan, and headquarters at 1-1, Takashima 1-chome, Nishi-ku, Yokohama 220-8686; representative executive officer, president and CEO Ivan Espinosa; paid-in capital 605,813 million yen; 23,174 employees non-consolidated and 120,079 consolidated; stated business: making and selling automotive products, plus related activities. NO `parent` IS WRITTEN: the company outline names no parent company, and the Renault-Nissan-Mitsubishi Alliance appears on the site only as a navigation entry, not as an owner, so the field is left off rather than filled with an alliance name. NOT dissolved." }, "generations": [ { "id": "350-z33", "name": "Z33 (fifth-generation Z, 350Z / Fairlady Z)", "codes": [ "Z33" ], "year_start": 2002, "year_end": 2008, "derived": true, "from_variant": 0 } ], "provenance": [ { "field": "production_runs", "item": 0, "ref": "run-2002-2008", "url": "https://www.nissan-global.com/EN/HERITAGE_COLLECTION/284_fairlady_z_version_st.html", "accessed": "2026-10-10", "field_tier": "primary-manufacturer" }, { "field": "production_runs", "item": 0, "ref": "run-2002-2008", "url": "https://global.nissannews.com/en/releases/release-2a0702e6a87ace39439e9e572af5d370-020730-01", "accessed": "2026-10-10", "field_tier": "primary-manufacturer" }, { "field": "variants", "item": 0, "ref": "generation-z33-fifth-generation-z-350z-fairlady-z", "url": "https://www.nissan-global.com/EN/HERITAGE_COLLECTION/383_fairlady_z_roadster.html", "accessed": "2026-10-10", "field_tier": "primary-manufacturer" }, { "field": "variants", "item": 1, "ref": "body-roadster", "url": "https://www.nissan-global.com/EN/HERITAGE_COLLECTION/383_fairlady_z_roadster.html", "accessed": "2026-10-10", "field_tier": "primary-manufacturer" }, { "field": "variants", "item": 2, "ref": "engine-3-5-vq35de-v6", "url": "https://www.nissan-global.com/EN/HERITAGE_COLLECTION/383_fairlady_z_roadster.html", "accessed": "2026-10-10", "field_tier": "primary-manufacturer" }, { "field": "variants", "item": 2, "ref": "engine-3-5-vq35de-v6", "url": "https://global.nissannews.com/en/releases/release-2a0702e6a87ace39439e9e572af5d370-020730-01", "accessed": "2026-10-10", "field_tier": "primary-manufacturer" }, { "field": "note", "item": null, "ref": null, "url": "https://www.nissan-global.com/EN/HERITAGE_COLLECTION/2000.html", "accessed": "2026-10-10", "field_tier": "secondary-wikipedia" }, { "field": "note", "item": null, "ref": null, "url": "https://en.wikipedia.org/w/index.php?title=Nissan_350Z&action=raw", "accessed": "2026-10-10", "field_tier": "secondary-wikipedia", "tier": "secondary-wikipedia", "tier_inferred": true }, { "field": "relations", "item": 0, "ref": "market-name-of-car-nissan-fairlady-z", "url": "https://www.nissan-global.com/PDF/ff_fy01e15.pdf", "accessed": null, "field_tier": "primary-manufacturer" }, { "field": "generations", "item": 0, "ref": "350-z33", "url": "https://www.nissan-global.com/EN/HERITAGE_COLLECTION/383_fairlady_z_roadster.html", "accessed": "2026-10-10", "field_tier": "primary-manufacturer" } ], "make_provenance": [ { "field": "founded", "item": null, "ref": null, "url": "https://www.nissan-global.com/EN/COMPANY/PROFILE/", "accessed": "2026-09-12", "field_tier": "primary-manufacturer" }, { "field": "country", "item": null, "ref": null, "url": "https://www.nissan-global.com/EN/COMPANY/PROFILE/", "accessed": "2026-09-12", "field_tier": "primary-manufacturer" }, { "field": "website", "item": null, "ref": null, "url": "https://www.nissan-global.com/EN/COMPANY/PROFILE/", "accessed": "2026-09-12", "field_tier": "primary-manufacturer" }, { "field": "note", "item": null, "ref": null, "url": "https://www.nissan-global.com/EN/COMPANY/PROFILE/", "accessed": "2026-10-02", "field_tier": "primary-manufacturer" } ] }, "enrichment_gated": false, "dataset_version": "2026.10.3", "attribution": { "source": "VehiclesDB", "url": "https://vehiclesdb.com", "license": "Identity layer: CC-BY-4.0; enrichment/resolution: proprietary. Display requires visible credit — see https://vehiclesdb.com/legal/attribution", "dataset_version": "2026.10.3" } } }, "fb974ffa7e48679431af83bf11ef92ed": { "summary": "Free plan (enrichment gated)", "value": { "id": "car/bmw/3-0cs", "name": "3.0CS", "make": { "id": "bmw", "name": "BMW" }, "kind": "car", "body_type": "coupe", "availability": [ "nl", "nz" ], "regions": [ "eu", "oc" ], "popularity": { "global_decile": 5, "mass_decile": 5, "rarity": "average" }, "aliases": [], "former_ids": [ "car/bmw/30cs" ], "years": null, "era": "classic", "enrichment": null, "enrichment_gated": true, "upgrade_url": "https://vehiclesdb.com/pricing", "dataset_version": "2026.10.3", "attribution": { "source": "VehiclesDB", "url": "https://vehiclesdb.com", "license": "Identity layer: CC-BY-4.0; enrichment/resolution: proprietary. Display requires visible credit — see https://vehiclesdb.com/legal/attribution", "dataset_version": "2026.10.3" } } }, "652b4dc0535c89b96819b6ec3e4acc96": { "summary": "Unknown id", "value": { "error": "not_found" } }, "5885ca56f3ae3832187c699a2274d4c1": { "summary": "Requested color is rendered", "value": { "id": "car/renault/clio", "color": "blue", "requested_color": "blue", "palette": [ "black", "blue", "grey", "red", "white" ], "variants": { "sm": { "url": "https://vehiclesdb.com/rails/active_storage/representations/proxy/…/car-renault-clio-blue.png", "width": 320, "height": 180 }, "md": { "url": "https://vehiclesdb.com/rails/active_storage/representations/proxy/…/car-renault-clio-blue.png", "width": 640, "height": 360 }, "lg": { "url": "https://vehiclesdb.com/rails/active_storage/representations/proxy/…/car-renault-clio-blue.png", "width": 1280, "height": 720 } }, "format": "webp", "provenance": { "generated": true, "license_note": "Generated imagery for product use; see PRD-IMAGES." }, "attribution": { "source": "VehiclesDB", "url": "https://vehiclesdb.com", "license": "Identity layer: CC-BY-4.0; enrichment/resolution: proprietary. Display requires visible credit — see https://vehiclesdb.com/legal/attribution", "dataset_version": "2026.10.3" } } }, "42c2416f9ba6841f87de9a72d6b07198": { "summary": "Un-rendered color falls back honestly", "value": { "id": "car/seat/leon", "color": "grey", "requested_color": "red", "palette": [ "black", "green", "grey", "white" ], "variants": { "sm": { "url": "https://vehiclesdb.com/…", "width": 320, "height": 180 }, "md": { "url": "https://vehiclesdb.com/…", "width": 640, "height": 360 }, "lg": { "url": "https://vehiclesdb.com/…", "width": 1280, "height": 720 } }, "format": "webp", "provenance": { "generated": true, "license_note": "Generated imagery for product use; see PRD-IMAGES." } } }, "2d065b51a2d050f0b2214e8edd1e4df3": { "summary": "No imagery for this vehicle yet", "value": { "error": "no_image", "id": "car/volkswagen/passat" } }, "6c70e3924e1f19f2b0b6a2935f598fab": { "summary": "Color outside the canonical palette", "value": { "error": "unknown_color", "palette": [ "white", "black", "grey", "silver", "blue", "red", "green", "brown", "beige", "orange", "yellow", "gold", "purple", "other" ] } }, "ca75e032e55451e47b0adee79983834e": { "summary": "Reserved filter used", "value": { "error": "unsupported_filter", "filter": "year" } }, "ec6bd8e5577a73c328211f49a40150c7": { "summary": "Germany with the series list abridged to 2 of 13", "value": { "jurisdiction": { "code": "de", "name": "Germany", "country": "Germany", "authority": "Fahrzeug-Zulassungsverordnung (FZV) — Bundesministerium für Digitales und Verkehr", "series_count": 13 }, "series": [ { "id": "de-standard", "class": "standard", "pattern": "LL-LL 9999", "period": { "start": 1995 }, "categories": [ "car", "van", "truck", "bus", "motorcycle", "trailer" ], "background": "#FFFFFF", "foreground": "#000000", "render_url": "https://vehiclesdb.com/plates/de/de-standard.svg" }, { "id": "de-seasonal", "class": "seasonal", "pattern": "LL-LL 999", "period": { "start": 1997 }, "categories": [ "car", "van", "truck", "bus", "motorcycle", "trailer" ], "background": "#FFFFFF", "foreground": "#000000", "render_url": "https://vehiclesdb.com/plates/de/de-seasonal.svg" } ], "attribution": { "source": "VehiclesDB", "url": "https://vehiclesdb.com", "license": "Identity layer: CC-BY-4.0; enrichment/resolution: proprietary. Display requires visible credit — see https://vehiclesdb.com/legal/attribution", "dataset_version": "2026.10.3" } } }, "f1743063fbe64a04ba560a5d324aa768": { "summary": "Unknown jurisdiction code", "value": { "error": "not_found" } }, "a502fbc1da8c56fe40fcea35d55a21e2": { "summary": "Exact match so as_issued is null", "value": { "plate": "1234 BCD", "jurisdiction": { "code": "es", "name": "Spain", "country": "Spain", "authority": "Dirección General de Tráfico (DGT) — Reglamento General de Vehículos, RD 2822/1998, Anexo XVIII", "series_count": 19 }, "valid": true, "exact": true, "as_issued": null, "matches": [ { "id": "es-national-2000", "class": "standard", "pattern": "9999 LLL", "period": { "start": 2000 }, "categories": [ "car", "van", "truck", "bus", "motorcycle" ], "background": "#FFFFFF", "foreground": "#000000", "render_url": "https://vehiclesdb.com/plates/es/es-national-2000.svg?serial=1234+BCD" } ], "attribution": { "source": "VehiclesDB", "url": "https://vehiclesdb.com", "license": "Identity layer: CC-BY-4.0; enrichment/resolution: proprietary. Display requires visible credit — see https://vehiclesdb.com/legal/attribution", "dataset_version": "2026.10.3" } } }, "6daccbbabe8cb64f20a92c01f850f9ef": { "summary": "Lenient match with separators forgiven", "value": { "plate": "12GBBD", "jurisdiction": { "code": "nl", "name": "Netherlands", "country": "Netherlands", "authority": "RDW (Dienst Wegverkeer)", "series_count": 33 }, "valid": true, "exact": false, "as_issued": "12-GB-BD", "matches": [ { "id": "nl-sidecode6-car", "class": "standard", "pattern": "99-LL-LL", "period": { "start": 2000 }, "categories": [ "car" ], "background": "#F9B700", "foreground": "#000000", "render_url": "https://vehiclesdb.com/plates/nl/nl-sidecode6-car.svg?serial=12GBBD" }, { "id": "nl-export", "class": "export", "pattern": "LLL-99-L", "period": { "start": 1951 }, "categories": [ "car", "van", "truck", "bus", "motorcycle", "moped", "trailer", "semitrailer", "tractor", "machine" ], "background": "#FFFFFF", "foreground": "#000000", "render_url": "https://vehiclesdb.com/plates/nl/nl-export.svg?serial=12GBBD" }, { "id": "nl-historic-darkblue-agricultural", "class": "historic", "pattern": "LLL-99-L", "period": { "start": 1978 }, "categories": [ "tractor", "machine", "trailer" ], "background": "#1D2E5B", "foreground": "#FFFFFF", "render_url": "https://vehiclesdb.com/plates/nl/nl-historic-darkblue-agricultural.svg?serial=12GBBD" } ], "attribution": { "source": "VehiclesDB", "url": "https://vehiclesdb.com", "license": "Identity layer: CC-BY-4.0; enrichment/resolution: proprietary. Display requires visible credit — see https://vehiclesdb.com/legal/attribution", "dataset_version": "2026.10.3" } } }, "d26a7f00336ab88ce1228aad823b80cf": { "summary": "Missing plate parameter", "value": { "error": "missing_plate", "message": "Pass ?plate=… — the registration to test." } }, "2bcdcd7c08284179fb10c9889da18022": { "summary": "Cars sold in Germany", "value": { "makes": [ { "name": "Alfa Romeo", "slug": "alfa-romeo", "kinds": [ "car" ] }, { "name": "Alpine", "slug": "alpine", "kinds": [ "car" ] } ], "count": 2, "dataset_version": "2026.10.3", "attribution": { "source": "VehiclesDB", "url": "https://vehiclesdb.com", "license": "Identity layer: CC-BY-4.0; enrichment/resolution: proprietary. Display requires visible credit — see https://vehiclesdb.com/legal/attribution", "dataset_version": "2026.10.3" } } }, "37a4717e9bcbd37e11eb01dbf236149d": { "summary": "Unknown kind", "value": { "error": "unknown_kind", "message": "Unknown kind \"boat\". Valid kinds: car, motorcycle, moped, van, truck, bus." } }, "dd64d33cda20d996e43e036773e3abf0": { "summary": "Origin not allowed", "value": { "error": "origin_not_allowed", "message": "This API key only works from the websites its owner allowed. Browser requests must come from one of those sites (the Origin or Referer header); a bare domain and its www. form both count. From a server, script or curl, use your private key (vdb_sk_…) instead. Manage allowed websites at https://vehiclesdb.com/settings/api-keys.", "origin": "www.example.com" } }, "70df45c095a20d89d08f67710ad30f94": { "summary": "Audi", "value": { "make": { "name": "Audi", "slug": "audi", "kinds": [ "car" ], "model_count": 65, "popularity_rank": 38, "models_url": "https://vehiclesdb.com/api/v1/makes/audi/models", "logo_url": "https://vehiclesdb.com/api/v1/makes/audi/logo" }, "dataset_version": "2026.10.3", "attribution": { "source": "VehiclesDB", "url": "https://vehiclesdb.com", "license": "Identity layer: CC-BY-4.0; enrichment/resolution: proprietary. Display requires visible credit — see https://vehiclesdb.com/legal/attribution", "dataset_version": "2026.10.3" } } }, "b5f69419e51e76c08c3c0402a13ec397": { "summary": "Unknown make", "value": { "error": "not_found" } }, "e398301f316725a8722c441a72c35449": { "summary": "Audi's models, most popular first", "value": { "make": { "name": "Audi", "slug": "audi" }, "models": [ { "name": "A1", "slug": "a1", "kind": "car", "body_type": "hatchback", "popularity_decile": 2, "years_on_record": { "first": 1986, "last": 2026 } }, { "name": "A3", "slug": "a3", "kind": "car", "body_type": "hatchback", "popularity_decile": 2, "years_on_record": { "first": 1996, "last": 2026 } } ], "count": 2, "dataset_version": "2026.10.3", "attribution": { "source": "VehiclesDB", "url": "https://vehiclesdb.com", "license": "Identity layer: CC-BY-4.0; enrichment/resolution: proprietary. Display requires visible credit — see https://vehiclesdb.com/legal/attribution", "dataset_version": "2026.10.3" } } }, "8be1b3f2363ff979ce0b3011396ff5e6": { "summary": "Unknown country", "value": { "error": "unknown_country", "message": "Unknown country \"xx\". Valid codes: ar, au, ca, ch, de, es, fi, gb, ie, lu, my, nl, no, nz, th, ua, us." } }, "cc715cb2365b25fab05e4f466feb2085": { "summary": "No logo for this make", "value": { "error": "logo_not_available", "message": "No logo is served for this make. Render your text fallback. The make name is the identifier that always works." } }, "001cabc7906748e72c2688fd79d8f9fe": { "summary": "Searching for the Golf", "value": { "query": "golf", "results": [ { "name": "Golf", "slug": "golf", "kind": "car", "make": { "name": "Volkswagen", "slug": "volkswagen" }, "body_type": "hatchback", "popularity_decile": 2 } ], "count": 1, "dataset_version": "2026.10.3", "attribution": { "source": "VehiclesDB", "url": "https://vehiclesdb.com", "license": "Identity layer: CC-BY-4.0; enrichment/resolution: proprietary. Display requires visible credit — see https://vehiclesdb.com/legal/attribution", "dataset_version": "2026.10.3" } } }, "442b17797b18fc06a63cf24664537395": { "summary": "A misspelled make, corrected", "value": { "query": "marcedes gla", "results": [ { "name": "GLA", "slug": "gla", "kind": "car", "make": { "name": "Mercedes-Benz", "slug": "mercedes-benz" }, "body_type": "suv", "popularity_decile": 2 } ], "count": 1, "dataset_version": "2026.10.3", "corrected_query": "Mercedes-Benz gla", "attribution": { "source": "VehiclesDB", "url": "https://vehiclesdb.com", "license": "Identity layer: CC-BY-4.0; enrichment/resolution: proprietary. Display requires visible credit — see https://vehiclesdb.com/legal/attribution", "dataset_version": "2026.10.3" } } }, "c646358c4f318202e18a1b6db3e88146": { "summary": "Missing query", "value": { "error": "missing_query", "message": "Pass ?q=… — what the person typed." } }, "8cf4d0020748753eb481337a61b8844c": { "summary": "One make of the tree", "value": { "makes": [ { "name": "Abarth", "slug": "abarth", "kinds": [ "car" ], "models": [ { "name": "500", "slug": "500", "kind": "car", "body_type": "hatchback", "popularity_decile": 5 }, { "name": "595", "slug": "595", "kind": "car", "body_type": "hatchback", "popularity_decile": 5 } ] } ], "count": 1, "model_count": 2, "dataset_version": "2026.10.3", "attribution": { "source": "VehiclesDB", "url": "https://vehiclesdb.com", "license": "Identity layer: CC-BY-4.0; enrichment/resolution: proprietary. Display requires visible credit — see https://vehiclesdb.com/legal/attribution", "dataset_version": "2026.10.3" } } } }, "links": {}, "callbacks": {} }, "servers": [ { "url": "https://vehiclesdb.com/api/v1", "description": "Production API" } ], "security": [ { "bearer": [] } ], "paths": { "/resolve": { "post": { "tags": [ "Resolve" ], "summary": "Resolve a vehicle string", "description": "Turns a messy vehicle string — a registry row, an insurance policy line, a\nmarketplace listing title — into a **canonical VehiclesDB id**, with a\nconfidence, machine-readable audit trail, and honest failure.\n\nThe resolution ladder, strongest rung first: exact canonical id →\n`former_ids` (id migration aliases) → make + model with alias folding →\nbare published alias (only when unambiguous) → a misspelled make + model\n(`\"method\": \"fuzzy\"`, confidence 0.8, only once every exact rung has\nmissed, and only when one make is clearly the closest). Below the **confidence\nfloor of 0.30 nothing is ever claimed as a match**: you get\n`\"match\": null` plus ranked `alternates` you can offer a human. A bare\nmodel name without a make (\"golf\") is deliberately unresolved — names\nneed makes; published aliases don't.\n\n`resolved_via` is the audit trail — every transformation the input went\nthrough (`make_alias:vw→volkswagen`, `make_typo:marcedes→mercedes-benz`,\n`former_id:…`, `kind_hint:van`), in\norder. Log it next to your stored id and every resolution is explainable\nlater.\n\nKind collisions (\"Mercedes-Benz Sprinter\" exists as van, bus and truck)\nbreak deterministically by popularity → availability breadth → kind\norder — pass `kind_hint` to pick your lane. `country_hint` prefers models\nwith official-register evidence in that country.\n\nCosts **1 credit** per call, resolved or honestly-unresolved (the ladder\nran either way); malformed requests (422) are free. Unresolved inputs are\nlogged to improve the resolver corpus — send `\"private\": true` to opt a\nrequest out of that log.", "operationId": "POST_resolve", "requestBody": { "$ref": "#/components/requestBodies/92252243ccdb43db1df9f5a01e39fa7d" }, "responses": { "200": { "$ref": "#/components/responses/f71d55f4a8d031af994a00bcc4aacdb3" }, "401": { "$ref": "#/components/responses/5e0b490756ac5ced147b298cf34b8d34" }, "403": { "$ref": "#/components/responses/42cb92148ba6af17e566a475c0d4c61a" }, "402": { "$ref": "#/components/responses/696d51887e34eea508345e4531b2c8fc" }, "422": { "$ref": "#/components/responses/81e4083ad712327fc36264a24317d334" }, "429": { "description": "Too many requests. Abuse ceiling, not your plan's quota — your credits are untouched. Retry after the window closes.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying — the limiter's window length.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "retry_after": { "type": "integer" } }, "required": [ "error", "message", "retry_after" ] }, "example": { "error": "rate_limited", "message": "Too many requests. This endpoint accepts 600 requests per 1 minute; retry in 60 seconds. This is an abuse limit, not your plan's quota — your credits are untouched.", "retry_after": 60 } } } } }, "security": [ { "bearer": [] } ], "deprecated": false } }, "/me": { "get": { "tags": [ "Account" ], "summary": "Check your API key", "description": "Returns everything you need to confirm a key is live and pointed at the\nright account: which key it is (name + masked token — never the secret\nitself, which exists in plaintext only at creation time), which plan and\nworkspace it bills, how many credits are left, and which dataset version\nyou're reading.\n\n**This call is **free****, always. Point your health checks and your\nonboarding \"test your key\" button here without watching the meter. Every\nother endpoint spends from the wallet; see each one for what it costs.\n\nA revoked, expired or unknown key gets 401 here exactly as it would\nanywhere else, which makes this the cheapest possible key liveness probe.", "operationId": "GET_me", "responses": { "200": { "$ref": "#/components/responses/039f5e9a1470229b189a4118a03484d2" }, "401": { "$ref": "#/components/responses/0f594d7485ff2eebc74c835a7a586d2e" }, "403": { "$ref": "#/components/responses/42cb92148ba6af17e566a475c0d4c61a" }, "429": { "description": "Too many requests. Abuse ceiling, not your plan's quota — your credits are untouched. Retry after the window closes.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying — the limiter's window length.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "retry_after": { "type": "integer" } }, "required": [ "error", "message", "retry_after" ] }, "example": { "error": "rate_limited", "message": "Too many requests. This endpoint accepts 600 requests per 1 minute; retry in 60 seconds. This is an abuse limit, not your plan's quota — your credits are untouched.", "retry_after": 60 } } } } }, "security": [ { "bearer": [] } ], "deprecated": false } }, "/vehicles/{kind}/{make_slug}/{model_slug}/full": { "get": { "tags": [ "Vehicle Records" ], "summary": "Get the full vehicle record", "description": "The complete record for one model, addressed by **canonical VehiclesDB\nid** (`kind/make_slug/model_slug` — resolve messy strings first with\n`POST /api/v1/resolve`).\n\n**Open identity fields** (every plan): name, make, kind, body type,\nper-country availability evidence, popularity deciles and rarity,\npublished aliases, `former_ids` (migration aliases — check these before\nassuming a stored id disappeared), year evidence, and `era`, the one\nenrichment teaser field.\n\nPopularity carries two deciles (1 = the top tenth). `global_decile` is a\npresence average: the mean of the model's per-country deciles, so it\nsays \"popular in many places\". `mass_decile` ranks the model among its\nkind by registrations summed across the registers, so it says \"how many\nexist\". `mass_decile` is null on dataset versions that predate it (check\n`dataset_version`), and for unranked models.\n\n**Enrichment** (plans with the `full_attributes` feature, Developer and\nup): curated production runs (with per-run notes), generations,\nvariant/trim taxonomy, reference links, relations (related models:\nrebadges, market names, predecessors, successors; `id` is the canonical\nid, or null when the related vehicle has no record in the catalog),\npowertrains (register-observed powertrain counts per country, with a\n`basis` id and a plain-language `basis_note` saying what that register\ncounts; never sum across countries), make-level facts (founded/dissolved/\ncountry/parent/website), and the sources behind all of it. When your plan\ndoesn't include it, the response says so honestly: `\"enrichment\": null,\n\"enrichment_gated\": true`, and the fields never silently vanish.\n\n**Row ids.** Every production run, variant, generation and relation row\ncarries a stable id derived from its content (`run-1996-2006`,\n`a3-8l`): `id` on runs, variants and generations, `row_id` on relations\n(whose `id` is the related vehicle). It survives re-ordering; a change to\nthe fact itself (its years, its name) is a different fact with a\ndifferent id.\n\n**Generations** come with the same years as production runs: `year_end`\nis the last year, `ended: true` without one means over but the last year\nis not yet sourced, and neither means still in production. `derived:\ntrue` marks a generation promoted from the record's `type: generation`\nvariant at index `from_variant`. Most records have none yet: the array\nis then empty.\n\n**Sources.** `provenance` holds one row per citation on this record and\n`make_provenance` the same for the make's facts (`make_facts` itself is\nunchanged). `ref` joins a citation to the exact row it cites: select the\nrows whose `ref` equals a run's, variant's or generation's `id`, or a\nrelation's `row_id`. A citation with a `field` and a null `ref` covers\nthat whole field (a make fact, a link, the note, or every row of a\nsection); a null `field` covers the whole record. `field_tier` is the\ncurator's evidence tier for the field; when it is ABSENT the fact is\ncited with its tier unknown, a source you can check that nobody graded.\n`tier: \"secondary-wikipedia\"` (with `tier_inferred: true`) is inferred\nfrom a Wikipedia URL, never curated. A fact with NO row at all, neither\nits own nor its field's, is unsourced: we hold no citation for it yet.\nLinks are the exception, since a link is its own source.\n\nCosts **2 credits** per call — the enriched record is the deepest read on the\nsurface and priced accordingly. Unknown ids (404) are free.", "operationId": "GET_vehicles_kind_make_slug_model_slug_full", "parameters": [ { "$ref": "#/components/parameters/770a251473e34d3bfea73ec9a34c74c3" }, { "$ref": "#/components/parameters/d8229c95093aac91811f8d163a1671c6" }, { "$ref": "#/components/parameters/model_slug" } ], "responses": { "200": { "$ref": "#/components/responses/9d8630a30ca9d5271f753a28f54289f7" }, "401": { "$ref": "#/components/responses/5e0b490756ac5ced147b298cf34b8d34" }, "403": { "$ref": "#/components/responses/42cb92148ba6af17e566a475c0d4c61a" }, "402": { "$ref": "#/components/responses/696d51887e34eea508345e4531b2c8fc" }, "404": { "$ref": "#/components/responses/b8d681f089b6b5ccb511487c7ac6350b" }, "429": { "description": "Too many requests. Abuse ceiling, not your plan's quota — your credits are untouched. Retry after the window closes.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying — the limiter's window length.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "retry_after": { "type": "integer" } }, "required": [ "error", "message", "retry_after" ] }, "example": { "error": "rate_limited", "message": "Too many requests. This endpoint accepts 600 requests per 1 minute; retry in 60 seconds. This is an abuse limit, not your plan's quota — your credits are untouched.", "retry_after": 60 } } } } }, "security": [ { "bearer": [] } ], "deprecated": false } }, "/vehicles/{kind}/{make_slug}/{model_slug}/images": { "get": { "tags": [ "Vehicle Images" ], "summary": "Get vehicle images", "description": "Returns rendered imagery for one vehicle model — studio-style renders on a\ntransparent background (pure alpha cutouts, no baked shadow: add depth\nwith CSS `filter: drop-shadow(...)` if your surface wants it), in three\nready-to-embed sizes.\n\nVehicles are addressed by their **canonical VehiclesDB id**: `kind/make_slug/model_slug`\n(e.g. `car/renault/clio`), the same slugs the open dataset and the\n[`vehicles` gem](https://github.com/vehiclesdb/vehicles) use — resolve free-text\nnames with the gem (`Vehicles.model(\"Renault\", \"Clío\")`) before calling this endpoint.\n\n**Colors** use the canonical 14-color VehiclesDB palette (`white`, `black`,\n`grey`, `silver`, `blue`, `red`, `green`, `brown`, `beige`, `orange`,\n`yellow`, `gold`, `purple`, `other`). Color matching is **honest by\ndesign**: request a color that exists for the model and you get it; request\none that isn't rendered yet and the API serves the closest sensible\nfallback (grey, else the first rendered color) — `color` in the response is\nalways what was actually served, `requested_color` what you asked for.\nA color outside the palette is a 422, never a silent guess.\n\n**Variant URLs are signed and key-free**: embed them directly in ``\n— your API key never needs to appear in markup. Variants are webp by\ndefault (`format=png` for PNG), served through the API host from private\nobject storage.\n\n`year` and `trim` are **reserved filters**: they 422 today so no\nintegration silently builds on unimplemented semantics, and they will\nactivate once year-accurate renders ship — the response shape will not\nchange, only the imagery gets more specific.\n\nCosts **1 credit** per served response (misses — 404s and 422s — are\nfree). Out of credits → 402 with self-serve top-up options.", "operationId": "GET_vehicles_kind_make_slug_model_slug_images", "parameters": [ { "$ref": "#/components/parameters/770a251473e34d3bfea73ec9a34c74c3" }, { "$ref": "#/components/parameters/d8229c95093aac91811f8d163a1671c6" }, { "$ref": "#/components/parameters/model_slug" }, { "$ref": "#/components/parameters/color" }, { "$ref": "#/components/parameters/format" } ], "responses": { "200": { "$ref": "#/components/responses/4fe5bf3223c0a287d63b1793cad4b81b" }, "401": { "$ref": "#/components/responses/5e0b490756ac5ced147b298cf34b8d34" }, "403": { "$ref": "#/components/responses/42cb92148ba6af17e566a475c0d4c61a" }, "402": { "$ref": "#/components/responses/696d51887e34eea508345e4531b2c8fc" }, "404": { "$ref": "#/components/responses/f28e861f856a1931bf99aedb6e6f8a5d" }, "422": { "$ref": "#/components/responses/4253077089ffb25b30ce120c4f191c54" }, "429": { "description": "Too many requests. Abuse ceiling, not your plan's quota — your credits are untouched. Retry after the window closes.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying — the limiter's window length.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "retry_after": { "type": "integer" } }, "required": [ "error", "message", "retry_after" ] }, "example": { "error": "rate_limited", "message": "Too many requests. This endpoint accepts 600 requests per 1 minute; retry in 60 seconds. This is an abuse limit, not your plan's quota — your credits are untouched.", "retry_after": 60 } } } } }, "security": [ { "bearer": [] } ], "deprecated": false } }, "/plates/{code}": { "get": { "tags": [ "License Plates" ], "summary": "A jurisdiction's plate format corpus", "description": "Every registration series a jurisdiction has issued, as data: the format\n`pattern` (`L` = letter, `9` = digit), the `period` it ran, the vehicle\n`categories` it covers, its statutory colours, and a `render_url` that\ndraws a 1:1 SVG of that design.\n\nCodes are ISO-3166-ish — a country (`de`, `fr`, `nl`) or a subdivision\n(`us-ca`, `au-nsw`, `ca-sk`). Case-insensitive. An unknown code is a\n**free 404**: you never pay to learn you typo'd.\n\n`background` and `foreground` carry the statutory colours where the\nsource states them and `null` where it does not — the dataset does not\nguess. `series_count` is the size of the full corpus for that\njurisdiction, which is what `series` contains.\n\n`render_url` is the same parametric SVG endpoint the site uses; add\n`?serial=…` to draw a specific registration on that design.\n\nCosts **5 credits** per served response: this returns a jurisdiction's ENTIRE\nformat corpus in one call, so it is priced as the bulk read it is. 404s are\nfree. Out of credits → 402 with self-serve top-up options.", "operationId": "GET_plates_code", "parameters": [ { "$ref": "#/components/parameters/code" } ], "responses": { "200": { "$ref": "#/components/responses/3c29ac8ebdc307939f076d8cade0cda2" }, "401": { "$ref": "#/components/responses/5e0b490756ac5ced147b298cf34b8d34" }, "403": { "$ref": "#/components/responses/42cb92148ba6af17e566a475c0d4c61a" }, "402": { "$ref": "#/components/responses/696d51887e34eea508345e4531b2c8fc" }, "404": { "$ref": "#/components/responses/7db1fa052774f7fe62f612a9f5d1b72d" }, "429": { "description": "Too many requests. Abuse ceiling, not your plan's quota — your credits are untouched. Retry after the window closes.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying — the limiter's window length.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "retry_after": { "type": "integer" } }, "required": [ "error", "message", "retry_after" ] }, "example": { "error": "rate_limited", "message": "Too many requests. This endpoint accepts 600 requests per 1 minute; retry in 60 seconds. This is an abuse limit, not your plan's quota — your credits are untouched.", "retry_after": 60 } } } } }, "security": [ { "bearer": [] } ], "deprecated": false } }, "/plates/{code}/match": { "get": { "tags": [ "License Plates" ], "summary": "Match a registration against a jurisdiction's formats", "description": "The two-tier matcher: **exact** (the plate exactly as the authority\nissues it, separators included) and **lenient** (separators forgiven —\nthe alphabet never is). `valid` is true when either tier matches;\n`exact` tells you which tier answered.\n\nWhen the typed form differs from the issued form, `as_issued` carries the\nreconstruction (`\"12GBBD\"` → `\"12-GB-BD\"`). On an exact match there is\nnothing to fix, so **`as_issued` is `null`** — read `exact` first, not the\npresence of `as_issued`. It is also `null` when the plate is invalid.\n\n`matches` is every series whose format accepts this registration —\nusually more than one, because standard, export, historic and seasonal\nseries often share a pattern. Each carries a `render_url` that draws\nTHAT registration on THAT design.\n\nAn unknown jurisdiction code is a free 404 and a missing `plate` a free\n422; both happen before metering. Costs **1 credit** per served answer,\nmatch or no match — the matcher ran either way.", "operationId": "GET_plates_code_match", "parameters": [ { "$ref": "#/components/parameters/code" }, { "$ref": "#/components/parameters/plate" } ], "responses": { "200": { "$ref": "#/components/responses/7e7bddcf7a2179819956bb1b7200f4a6" }, "401": { "$ref": "#/components/responses/5e0b490756ac5ced147b298cf34b8d34" }, "403": { "$ref": "#/components/responses/42cb92148ba6af17e566a475c0d4c61a" }, "402": { "$ref": "#/components/responses/696d51887e34eea508345e4531b2c8fc" }, "404": { "$ref": "#/components/responses/7db1fa052774f7fe62f612a9f5d1b72d" }, "422": { "$ref": "#/components/responses/54620957a0a3fde27fc1b610f98112fd" }, "429": { "description": "Too many requests. Abuse ceiling, not your plan's quota — your credits are untouched. Retry after the window closes.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying — the limiter's window length.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "retry_after": { "type": "integer" } }, "required": [ "error", "message", "retry_after" ] }, "example": { "error": "rate_limited", "message": "Too many requests. This endpoint accepts 600 requests per 1 minute; retry in 60 seconds. This is an abuse limit, not your plan's quota — your credits are untouched.", "retry_after": 60 } } } } }, "security": [ { "bearer": [] } ], "deprecated": false } }, "/makes": { "get": { "tags": [ "Dropdown Data" ], "summary": "List every make", "description": "The full make list — ~935 makes across cars, motorcycles, mopeds, vans,\ntrucks and buses, reconciled from official registers of 18 countries.\nAlphabetical, ~10 KB gzipped: fetch it once per pageview and populate a\n``\nchanges.\n\n`popularity_decile` ranks by real-world registrations (1 = the most\nregistered tenth globally, 10 = the rarest; null = unranked), so\n`?order=popular` puts the Golf above the 412 owners actually buy. With\n`country`, `popular` follows that country's own registration ranking\nfirst, wherever the dataset carries one: Ford in `gb` then opens with\nthe Fiesta, not the model that is popular in the most countries. Ranks\nare per kind, so pass `kind` too for one clean ranking. A dataset release\nwithout country ranks keeps the decile order.\n\n`years_on_record` is `{\"first\": …, \"last\": …}`, the first and last year the\nofficial registers have the model on record; null when none. That is the\nspan to offer in a year step after the model.\nThese are register years (the years cars of the model were first\nregistered), not production or model years: an import can be registered\nyears after it was built, and a model's oldest cars may have left the\nregister. That is why the field is not called `years`, which on the full\nrecord means production years.\n\nThis call is **free**, accepts your **public key** (`vdb_pk_…`, safe in a\nbrowser), and is privately cacheable — the same contract as the make list.\nThe ETag moves with the dataset version, and with the registration data\nthe years come from.", "operationId": "GET_makes_make_slug_models", "parameters": [ { "$ref": "#/components/parameters/213bd67811aeb10510c88a2dbb4bdbed" }, { "$ref": "#/components/parameters/eb436a0dd2958df386b3d676bf02ac52" }, { "$ref": "#/components/parameters/126579f3d7114c0ab098cb9f315f0128" }, { "$ref": "#/components/parameters/d2b4651ba8d60af148d0d3ea300b56f7" } ], "responses": { "200": { "$ref": "#/components/responses/03277160af6e4225c41cc4c1c5ea3dd5" }, "404": { "$ref": "#/components/responses/6b23d7ae15e1dc648a848579ad6a3076" }, "422": { "$ref": "#/components/responses/ed37dfa1449f133386ef76710e50df5e" }, "401": { "$ref": "#/components/responses/0f594d7485ff2eebc74c835a7a586d2e" }, "403": { "$ref": "#/components/responses/85fd2a698fdc496f66f981f3d398ff61" }, "429": { "description": "Too many requests. Abuse ceiling, not your plan's quota — your credits are untouched. Retry after the window closes.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying — the limiter's window length.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "retry_after": { "type": "integer" } }, "required": [ "error", "message", "retry_after" ] }, "example": { "error": "rate_limited", "message": "Too many requests. This endpoint accepts 600 requests per 1 minute; retry in 60 seconds. This is an abuse limit, not your plan's quota — your credits are untouched.", "retry_after": 60 } } } } }, "security": [ { "bearer": [] } ], "deprecated": false } }, "/makes/{make_slug}/logo": { "get": { "tags": [ "Dropdown Data" ], "summary": "A make's logo", "description": "The vendored logo for one make, as the image file itself (SVG for most).\nCoverage is partial and deliberate: only marques whose files carry\nrecorded provenance are served, and any marque can be withdrawn at any\ntime. **Always render the make's name next to the badge, and build the\ntext fallback first** — a 404 here is a normal answer, not an error (the\ndropdown library falls back to an initial-letter chip automatically).\n\nLogos are third-party trademarks. They are served for referential display\nof the make they identify, no license is granted, and they sit outside\nevery VehiclesDB indemnity — see the API terms.\n\nThis call is **free** and accepts your **public key** (`vdb_pk_…`, safe in\na browser).", "operationId": "GET_makes_make_slug_logo", "parameters": [ { "$ref": "#/components/parameters/213bd67811aeb10510c88a2dbb4bdbed" }, { "$ref": "#/components/parameters/variant" } ], "responses": { "200": { "$ref": "#/components/responses/f0ae0cbd151a7e3ae42c299dbb079603" }, "404": { "$ref": "#/components/responses/43d4678d59af17c7cd363c5d94d6b8e4" }, "401": { "$ref": "#/components/responses/0f594d7485ff2eebc74c835a7a586d2e" }, "403": { "$ref": "#/components/responses/85fd2a698fdc496f66f981f3d398ff61" }, "429": { "description": "Too many requests. Abuse ceiling, not your plan's quota — your credits are untouched. Retry after the window closes.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying — the limiter's window length.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "retry_after": { "type": "integer" } }, "required": [ "error", "message", "retry_after" ] }, "example": { "error": "rate_limited", "message": "Too many requests. This endpoint accepts 600 requests per 1 minute; retry in 60 seconds. This is an abuse limit, not your plan's quota — your credits are untouched.", "retry_after": 60 } } } } }, "security": [ { "bearer": [] } ], "deprecated": false } }, "/search": { "get": { "tags": [ "Dropdown Data" ], "summary": "Search makes and models", "description": "Substring search across every model in the catalog — the endpoint behind\nthe dropdown's searchable mode. Case and spacing are forgiving; results\nrank by match quality (exact name, then prefix, then substring), with\nshorter names breaking ties.\n\nTypos in the make are forgiven when the query would otherwise find\nnothing: `marcedes gla` (and `vw golf`, which no model's name contains)\nis searched again with the make spelled out, and the response carries\n`corrected_query` — the query the results are for, e.g.\n`Mercedes-Benz gla` — so you can say \"Showing results for …\" honestly.\nThe field is absent whenever the results match what was typed.\n\nResults are models (with their make attached), capped at 25 per call —\nthis is a typeahead, not an export. This call is **free** and accepts your\n**public key (also called a publishable key, `vdb_pk_…`)** — safe to ship\nin your website's code, spends nothing. Responses are ETagged per query,\nso repeated keystrokes can revalidate cheaply without bypassing the key or\nits origin lock.", "operationId": "GET_search", "parameters": [ { "$ref": "#/components/parameters/q" }, { "$ref": "#/components/parameters/61fa9560b7bd4d56c49fb058c2d7234c" } ], "responses": { "200": { "$ref": "#/components/responses/32ad41e02ec6088939c28e37c340b7f0" }, "422": { "$ref": "#/components/responses/a55bb0e8be1152a513b5ae79aa7efdac" }, "401": { "$ref": "#/components/responses/0f594d7485ff2eebc74c835a7a586d2e" }, "403": { "$ref": "#/components/responses/85fd2a698fdc496f66f981f3d398ff61" }, "429": { "description": "Too many requests. Abuse ceiling, not your plan's quota — your credits are untouched. Retry after the window closes.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying — the limiter's window length.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "retry_after": { "type": "integer" } }, "required": [ "error", "message", "retry_after" ] }, "example": { "error": "rate_limited", "message": "Too many requests. This endpoint accepts 600 requests per 1 minute; retry in 60 seconds. This is an abuse limit, not your plan's quota — your credits are untouched.", "retry_after": 60 } } } } }, "security": [ { "bearer": [] } ], "deprecated": false } }, "/catalog": { "get": { "tags": [ "Dropdown Data" ], "summary": "The whole catalog in one response", "description": "Every make with every one of its models, in one document: ~935 makes and\n~15k models across cars, motorcycles, mopeds, vans, trucks and buses,\nabout 1.5 MB (~165 KB gzipped). Fetch it once, keep it, and sync\nit on your own schedule: `dataset_version` tells you when it changed, and\na request carrying the last ETag in `If-None-Match` costs a 304 while it\nhas not.\n\nUse this instead of walking `/makes/{slug}/models` per make whenever you\nwant a local copy of the taxonomy: a validation table, an offline\ndropdown, a search index of your own.\n\nThis call is **free** and accepts your **public key (also called a\npublishable key, `vdb_pk_…`)**. The identity layer is CC-BY 4.0: keep the\nattribution object with the data, and show the credit where you show the\ndata.", "operationId": "GET_catalog", "parameters": [ { "$ref": "#/components/parameters/9839b2e79ab2f918f8c5295b0beb84ae" } ], "responses": { "200": { "$ref": "#/components/responses/9aa8146ffd22f73631f928f59ecdbacd" }, "422": { "$ref": "#/components/responses/7ba5ea796b1ca2aa817851cf275ff5a4" }, "401": { "$ref": "#/components/responses/0f594d7485ff2eebc74c835a7a586d2e" }, "403": { "$ref": "#/components/responses/85fd2a698fdc496f66f981f3d398ff61" }, "429": { "description": "Too many requests. Abuse ceiling, not your plan's quota — your credits are untouched. Retry after the window closes.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying — the limiter's window length.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "retry_after": { "type": "integer" } }, "required": [ "error", "message", "retry_after" ] }, "example": { "error": "rate_limited", "message": "Too many requests. This endpoint accepts 600 requests per 1 minute; retry in 60 seconds. This is an abuse limit, not your plan's quota — your credits are untouched.", "retry_after": 60 } } } } }, "security": [ { "bearer": [] } ], "deprecated": false } } }, "tags": [ { "name": "Resolve", "description": "Normalization-as-a-service: a messy vehicle string in, a canonical id, a confidence, ranked alternates and a `resolved_via` audit trail out. Resolve once, store the id, and every other endpoint becomes a lookup." }, { "name": "Vehicle Records", "description": "Everything we hold on one model. Identity fields — names, taxonomy, per-country register evidence, popularity, `former_ids` — are open on every plan; curated enrichment (production runs, generations, variants, links, related models, powertrain counts, make facts, and the source behind each fact) comes with the paid plans and is labelled gated, never silently dropped." }, { "name": "Vehicle Images", "description": "Rendered vehicle imagery: studio-style, color-accurate, ready-to-embed. Addressed by canonical VehiclesDB ids; the variant URLs come back signed, so your key never reaches a browser." }, { "name": "License Plates", "description": "The world's registration formats — validation, as-issued formatting, and 1:1 SVG renders, from the same statute-sourced dataset that powers vehiclesdb.com/license-plates." }, { "name": "Dropdown Data", "description": "The endpoints behind the make-model-dropdown widget (vehiclesdb.com/make-and-model-dropdown): make lists, one make, per-make model lists, the whole catalog in one call, typeahead search and make logos. They are free, they never spend a credit, and they accept your public key (also called a publishable key, `vdb_pk_`), the one that is safe to put in a website where anyone can see it. ETagged for efficient browser revalidation, so they are also the friendliest way to populate any vehicle picker of your own." }, { "name": "Account", "description": "Your key, your plan, your credit balance. The one free call on the surface — a key check should never cost a credit, so point health checks and onboarding here." } ] }