API reference / OpenAPI schemasOpenAPI YAML ↗
Beta
AutoUncle Data Services is in beta. The API, MCP tools and agent skill may change often, including breaking changes, until version 1.0. Read the changelog before you upgrade an integration.
OpenAPI schemas
Country-specific professional vehicle valuations, vehicle identification and the vehicle catalogue. Every endpoint that describes a vehicle returns it as an AutoUncle Vehicle Schema (AVS) 0.3 vehicle document, with the catalogue identification and per-field provenance beside it in `identification`, and every request that describes one accepts that document back as its vehicle. Test keys return simulated valuations and synthetic lookups without spending credits. Live requests spend one credit only when successful. Every result carries notes[] (standing limitations, disclaimers and legal notices) and attributions[] (only the data sources that contributed, with licence references and any required attribution text).
Version 0.9.0 · OpenAPI 3.1.0
Shared schemas
Request and response definitions reference these shared schemas. Expand one to see its JSON Schema.
ValuationRequest
{
"type": "object",
"properties": {
"country": {
"type": "string",
"maxLength": 10,
"minLength": 2,
"description": "Valuation market as an ISO 3166-1 alpha-2 code, such as DK, DE or GB. The market selects its own vehicle data, currency and mileage conventions."
},
"vehicle": {
"$ref": "#/components/schemas/VehicleInput",
"description": "The vehicle, as a VehicleInput: an AVS vehicle document (any `vehicle` an endpoint returned, posted back unchanged) or the vehicle's attributes as a listing gives them."
},
"description": {
"type": "string",
"maxLength": 20000,
"minLength": 1,
"description": "Unstructured listing text describing the vehicle. Existing parsers and deployment-configured optional AI can propose attributes; the response identifies assumptions and unresolved inputs."
},
"images": {
"type": "array",
"minItems": 1,
"maxItems": 8,
"items": {
"type": "object",
"properties": {
"url": {
"type": "string",
"maxLength": 2048,
"format": "uri",
"description": "Public HTTPS image URL on port 443, without credentials or fragments. Private network destinations and redirects are rejected. Remote images must be supported image types and at most 8 MB each."
},
"data": {
"type": "string",
"maxLength": 1000000,
"description": "Strict base64-encoded image bytes, without a data-URL prefix. Inline data must also fit the total 1 MB API request limit."
},
"media_type": {
"type": "string",
"maxLength": 100,
"description": "MIME type for inline image bytes: image/jpeg, image/png, image/webp or image/gif. The actual image signature is checked."
}
},
"additionalProperties": false,
"anyOf": [
{
"required": [
"url"
]
},
{
"required": [
"data",
"media_type"
]
}
]
},
"description": "Up to eight vehicle photos, each supplied by HTTPS URL or inline base64 data. AI image resolution is deployment-configured and never runs for test keys. Warnings identify unused images. On a live key, photos cost one extra credit per request (not per photo), charged only when the request succeeds and a value was read from them (`usage.charges.images`); skipped or unused photos are not charged."
},
"pricing": {
"type": "object",
"properties": {
"price_basis": {
"type": "string",
"maxLength": 200,
"enum": [
"dealer_retail",
"private_sale"
],
"description": "dealer_retail estimates a freshly listed dealer asking price; private_sale estimates a private seller asking price. These are not guaranteed transaction or trade-in prices."
},
"seller_region": {
"type": "string",
"maxLength": 120,
"description": "Known seller region within the selected market. This is passed as regional pricing context when available."
},
"asking_price": {
"type": "number",
"minimum": 0,
"maximum": 100000000,
"description": "Optional asking price in the market currency. Used to calculate AutoUncle price ratings and rating stability across the uncertainty interval."
}
},
"additionalProperties": false,
"description": "The asking-price context for this valuation. The result explicitly states its currency and whether the expected asking price is dealer retail or private sale."
},
"options": {
"type": "object",
"properties": {
"resolution": {
"type": "string",
"maxLength": 200,
"enum": [
"auto",
"no_ai",
"strict"
],
"description": "auto uses deterministic resolution and optional configured AI; no_ai uses deterministic resolution only; strict disables AI and refuses missing registration year or mileage. Mileage is never assumed without allow_mileage_estimation=true, and strict mode overrides that permission. Configured live AI is invoked only for missing identity/year or core drivetrain attributes, catalogue candidates the deterministic matcher cannot separate, equipment or condition the request does not supply, and whenever images are sent (for the equipment, colour, condition and drive side they show). An image that cannot be read is skipped with an image_skipped warning. Once invoked, a dependency timeout or outage fails the valuation; it is never silently treated as successful enrichment."
},
"min_precision": {
"type": "string",
"maxLength": 200,
"enum": [
"high",
"medium",
"low",
"indicative"
],
"description": "Minimum acceptable precision grade. If the result falls below this grade, the request is refused without consuming a credit. Sandbox results are indicative."
},
"include": {
"type": "array",
"maxItems": 10,
"items": {
"type": "string",
"maxLength": 100,
"enum": [
"comparables",
"trade_in_price",
"similar_cars_link"
]
},
"description": "Optional response sections to add. A section never changes the price, intervals or precision. `comparables` adds up to five comparable listings on sale and five recently sold in the same market, with top-level facts only, as supporting evidence for the valuation (see `comparables` in the response). One extra credit on a live key, charged only when listings are returned (`comparables.status` `included`) and released otherwise. Unavailable in Denmark, where the response says so with a note instead. `trade_in_price` adds AutoUncle's estimate of a fair trade-in price with a range (see `trade_in_price` in the response). One extra credit on a live key, charged only when it is returned (`trade_in_price.status` `included`). Available in AT, CH, DE, DK, ES, FR, GB, IT, NL, PL, PT and SE; in other markets the response says so with a note and nothing is charged. `similar_cars_link` adds `similar_cars_url`, a link to similar cars for sale on the market's AutoUncle site. Free, in every market.",
"uniqueItems": true
},
"allow_mileage_estimation": {
"type": "boolean",
"default": false,
"description": "Explicitly allow a fixed 96,000 km baseline when mileage cannot be extracted or supplied. This is an assumption, not a vehicle-specific estimate; it lowers precision. Default false. Strict resolution still refuses missing mileage."
},
"allow_equipment_estimation": {
"type": "boolean",
"default": false,
"description": "Explicitly allow equipment the request does not state to be assumed: the catalogue's equipment for the identified trim when the catalogue lists it, otherwise the equipment at least 70% of comparable vehicles on the market have. Assumed equipment is only added, never against equipment the request, its description or its photos state or deny, and is marked source imputed, basis assumed in identification.fields (availability unknown in vehicle.equipment), with an equipment_assumed warning and an improve_precision hint. Like any assumption it lowers precision to low. Test keys use only the catalogue trim, never market data. Default false. Strict resolution ignores it."
}
},
"additionalProperties": false,
"description": "Resolution and minimum precision controls. Missing optional values use the documented default behaviour."
}
},
"additionalProperties": false,
"required": [
"country"
],
"anyOf": [
{
"required": [
"vehicle"
],
"properties": {
"vehicle": {
"minProperties": 1
}
}
},
{
"required": [
"description"
]
},
{
"required": [
"images"
]
}
],
"description": "A valuation request for one market. Provide structured vehicle attributes, listing text or photos; unknown inputs are reflected in uncertainty, provenance and improvement hints."
}VehicleInput
{
"description": "A vehicle as a request describes it: either an AVS vehicle document (any `vehicle` an endpoint returned, posted back unchanged, or one you build), recognized by its `avs` member, or the vehicle's attributes (VehicleAttributes). Omit unknown values instead of guessing.",
"if": {
"type": "object",
"required": [
"avs"
]
},
"then": {
"$ref": "#/components/schemas/Vehicle"
},
"else": {
"$ref": "#/components/schemas/VehicleAttributes"
}
}VehicleAttributes
{
"type": "object",
"additionalProperties": false,
"description": "A vehicle described by its attributes: the listing-style fields (make, model, fuel, power_hp, catalogue IDs and so on) for integrations that only have listing data. The canonical groups (identity, specs, registration, listing, equipment) are the vehicle as contract versions before 0.9.0 returned it, still accepted. When both set the same value, the canonical group wins and a vehicle_input_overridden warning names the loose field. A catalogue ID wins over a name at the same level. Omit unknown values instead of guessing; explicit attributes take precedence over inferred values.",
"properties": {
"make": {
"type": "string",
"maxLength": 200,
"description": "Vehicle manufacturer or make, such as VW or BMW. Catalogue brand_id avoids ambiguous names."
},
"model": {
"type": "string",
"maxLength": 200,
"description": "Model name as supplied by your source, such as Golf. Catalogue model_id avoids name mapping and spelling ambiguity."
},
"variant": {
"type": "string",
"maxLength": 200,
"description": "Free-text engine, trim or version designation, such as 1.5 TSI DSG. This can help resolve a more precise catalogue identity."
},
"body": {
"type": "string",
"maxLength": 200,
"description": "Body style or source label, such as hatchback, estate or SUV. Unknown labels may remain unresolved."
},
"fuel": {
"type": "string",
"maxLength": 200,
"description": "Fuel or electrification type: petrol, diesel, electric, hybrid (a full hybrid that cannot be plugged in), plug_in_hybrid_petrol, plug_in_hybrid_diesel, lpg, cng, ethanol or hydrogen, as listed by /v1/catalogue/enums. Source labels are also normalized when recognized."
},
"color": {
"type": "string",
"maxLength": 200,
"description": "Exterior colour or colour family from your source. Colour is normalized when possible."
},
"catalogue": {
"type": "object",
"properties": {
"brand_id": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Make UUID returned by the brands catalogue endpoint. All lower-level IDs must belong to this make."
},
"model_id": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Model UUID returned by the models catalogue endpoint. Virtual model aliases are resolved to their canonical model for scoring."
},
"generation_id": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Generation UUID returned for the selected model. This identifies the vehicle generation and body variant."
},
"drivetrain_id": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Drivetrain UUID returned for the selected generation. Identifies the engine and transmission variant and improves identity precision."
},
"equipment_variant_id": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Equipment or trim variant UUID returned for the make. It must belong to the same make as the other catalogue IDs."
}
},
"additionalProperties": false,
"description": "Stable AutoUncle catalogue UUIDs. Supply any known levels; IDs must describe one consistent vehicle hierarchy."
},
"model_year": {
"type": "integer",
"minimum": 1900,
"maximum": 2100,
"description": "Known registration or model year as a four-digit integer. first_registration takes precedence when both are supplied."
},
"first_registration": {
"type": "string",
"maxLength": 10,
"format": "date",
"description": "First registration date in YYYY-MM-DD format. The current valuation payload uses its year; do not derive a registration date from a photograph."
},
"mileage": {
"type": "object",
"properties": {
"value": {
"type": "number",
"minimum": 0,
"maximum": 10000000,
"description": "Non-negative odometer reading in the accompanying unit. Do not convert it twice when changing the unit."
},
"unit": {
"type": "string",
"maxLength": 200,
"enum": [
"km",
"mi",
"mil"
],
"description": "Odometer unit: km means kilometres, mi means miles, and mil means Scandinavian miles of ten kilometres."
}
},
"additionalProperties": false,
"required": [
"value",
"unit"
],
"description": "Odometer value with an explicit unit. Values are converted to the requested market convention before scoring."
},
"transmission": {
"type": "string",
"maxLength": 200,
"enum": [
"manual",
"automatic"
],
"description": "Known transmission type, automatic or manual. Omit it when unknown; an omitted gearbox is not treated as manual."
},
"drive": {
"type": "string",
"maxLength": 200,
"enum": [
"fwd",
"rwd",
"2wd",
"awd",
"4wd"
],
"description": "Driven wheels: fwd, rwd, awd or 4wd, or 2wd when only two-wheel drive is known (the value catalogue drivetrains return for most cars). Use the value supported by the vehicle specification."
},
"power_hp": {
"type": "number",
"minimum": 0,
"maximum": 3000,
"description": "Engine or drivetrain power in horsepower. Convert a source value in kilowatts before submitting it here."
},
"engine_size_l": {
"type": "number",
"minimum": 0,
"maximum": 30,
"description": "Combustion engine displacement in litres, such as 1.5. Omit for a fully electric vehicle."
},
"battery_kwh": {
"type": "number",
"minimum": 0,
"maximum": 500,
"description": "Known traction battery capacity in kilowatt-hours. Omit when the source does not report a capacity."
},
"electric_range_km": {
"type": "number",
"minimum": 0,
"maximum": 3000,
"description": "Known electric driving range in kilometres, regardless of the odometer unit or valuation market."
},
"doors": {
"type": "integer",
"minimum": 1,
"maximum": 10,
"description": "Number of doors reported by the vehicle specification. Helps distinguish otherwise similar body variants."
},
"seats": {
"type": "integer",
"minimum": 1,
"maximum": 20,
"description": "Number of seats reported by the vehicle specification."
},
"condition": {
"type": "number",
"minimum": 0,
"maximum": 4,
"description": "Known numeric vehicle condition grade from 0 through 4. Omit unknown condition rather than inventing a grade."
},
"drive_side": {
"type": "string",
"maxLength": 200,
"enum": [
"left",
"right"
],
"description": "Steering wheel position: left for left-hand drive and right for right-hand drive. This is not the side of the road used by traffic."
},
"flags": {
"type": "object",
"maxProperties": 30,
"additionalProperties": {
"type": "boolean"
},
"description": "Boolean risk and eligibility attributes. Only the documented keys have an effect: when one is true, the vehicle is outside the market's model and the valuation is refused with unsupported_vehicle (some keys only in the markets they name). false has the same effect as leaving the key out. Any other key is ignored with a flags_not_recognized warning, and a market-specific key sent for another market is ignored with a flags_not_applicable warning.",
"properties": {
"is_damaged": {
"type": "boolean",
"description": "The vehicle is damaged. When true the vehicle is refused with unsupported_vehicle in every market."
},
"has_new_engine": {
"type": "boolean",
"description": "The engine has been replaced. When true the vehicle is refused with unsupported_vehicle in every market."
},
"is_leasing_price": {
"type": "boolean",
"description": "The price is a leasing price, not a sale price. When true the vehicle is refused with unsupported_vehicle in every market."
},
"has_no_battery": {
"type": "boolean",
"description": "An electric vehicle sold without its traction battery, for example under battery rental. When true the vehicle is refused with unsupported_vehicle in every market."
},
"is_auction_car": {
"type": "boolean",
"description": "The vehicle is sold at auction. When true the vehicle is refused with unsupported_vehicle in every market."
},
"is_commercial_car": {
"type": "boolean",
"description": "The vehicle is registered or sold as a commercial vehicle. When true the vehicle is refused with unsupported_vehicle in every market."
},
"price_is_leasing_rate": {
"type": "boolean",
"description": "The price is a periodic leasing rate, not a sale price. When true the vehicle is refused with unsupported_vehicle in every market."
},
"has_no_tax": {
"type": "boolean",
"description": "The price excludes registration tax. Applies in DK, SE, DE, ES, AT and PT, where true is refused with unsupported_vehicle."
},
"has_yellow_plates": {
"type": "boolean",
"description": "Registered on Danish yellow (commercial) plates. Applies in DK only, where true is refused with unsupported_vehicle."
},
"is_camper_version": {
"type": "boolean",
"description": "A camper conversion. Applies in DK only, where true is refused with unsupported_vehicle."
}
}
},
"equipment": {
"type": "array",
"maxItems": 150,
"items": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "object",
"additionalProperties": false,
"required": [
"key"
],
"properties": {
"key": {
"type": "string",
"maxLength": 100,
"description": "Feature key, such as `EXTERIOR_TOWBAR_FIXED`."
},
"availability": {
"type": "string",
"maxLength": 100,
"description": "Read-only. Ignored."
},
"id": {
"type": "string",
"maxLength": 200,
"description": "Read-only. Ignored."
},
"name": {
"type": "string",
"maxLength": 200,
"description": "Read-only. Ignored."
},
"category": {
"type": "string",
"maxLength": 200,
"description": "Read-only. Ignored."
}
}
}
]
},
"description": "Known equipment as feature keys from /v1/catalogue/enums, such as `EXTERIOR_TOWBAR_FIXED` or `INFOTAINMENT_NAVIGATION`, as strings or as the items of a returned Vehicle. The earlier keys such as `has_tow_bar` are still accepted. Unrecognized keys produce a warning."
},
"vin": {
"type": "string",
"maxLength": 30,
"description": "Optional vehicle identification number; the same as `registration.vin`. Live keys look it up: in DK in the Danish Motor Register, elsewhere with VIN decoding (make, model and model year). Never looked up in DE, IT or ES, or with test keys. Looked-up values only fill attributes you leave out and are identified against the catalogue like your own; their provenance in `identification.fields` has source registry and a source_id. A value that disagrees with one you supplied gives a registry_conflict warning while yours is used. If the lookup cannot be used, your other attributes are used and a warning says why. Included in the request's credit. The raw VIN is not retained."
},
"registration_plate": {
"type": "string",
"maxLength": 30,
"description": "Optional registration plate; the same as `registration.registration_plate`. Live keys look it up in the national register where one is connected (DK, the Danish Motor Register); elsewhere it gives a registry_lookup_not_available warning, and a vin sent with it is still decoded. Looked-up values only fill attributes you leave out, as for vin. The odometer reading of the last inspection is never used as the mileage. Included in the request's credit. The raw plate is not retained."
},
"identity": {
"type": "object",
"additionalProperties": false,
"description": "Canonical identity: a catalogue ID per level, or a brand and model name. Canonical form of `make`, `model`, `variant` and `catalogue`.",
"properties": {
"level": {
"type": "string",
"description": "Read-only part of a returned Vehicle. Accepted and ignored."
},
"brand": {
"$ref": "#/components/schemas/VehicleInputRef",
"description": "The brand: an `id` (like catalogue.brand_id) or a `name` (like make)."
},
"model": {
"$ref": "#/components/schemas/VehicleInputRef",
"description": "The model: an `id` (like catalogue.model_id) or a `name` (like model)."
},
"generation": {
"$ref": "#/components/schemas/VehicleInputRef",
"description": "The generation, by `id` (like catalogue.generation_id)."
},
"drivetrain": {
"$ref": "#/components/schemas/VehicleInputRef",
"description": "The drivetrain, by `id` (like catalogue.drivetrain_id). The drivetrain's specs win over supplied ones; contradictions are reported as conflicts."
},
"equipment_variant": {
"$ref": "#/components/schemas/VehicleInputRef",
"description": "The equipment variant, by `id` (like catalogue.equipment_variant_id)."
},
"variant_text": {
"type": "string",
"maxLength": 200,
"description": "Free-text engine, trim or version designation; the same as `variant`."
}
}
},
"specs": {
"$ref": "#/components/schemas/VehicleSpecs",
"description": "Canonical technical facts: `energy.fuel` for `fuel`, `power.hp` or `power.kw` for `power_hp`, `transmission.type` for `transmission`, `traction` for `drive`, and `body`, `doors`, `seats`, `engine_size_l`, `battery_kwh` and `electric_range_km` as named."
},
"registration": {
"type": "object",
"additionalProperties": false,
"description": "Canonical registration facts and identifiers. A VIN, plate or HSN/TSN pair is looked up as described for `vin`.",
"properties": {
"country": {
"type": "string",
"maxLength": 10,
"description": "Read-only part of a returned Vehicle. Ignored: the request's `country` is the market."
},
"first_registration": {
"type": "string",
"maxLength": 10,
"format": "date",
"description": "First registration date (YYYY-MM-DD); the same as `first_registration`."
},
"model_year": {
"type": "integer",
"minimum": 1900,
"maximum": 2100,
"description": "Model or registration year; the same as `model_year`."
},
"vin": {
"type": "string",
"maxLength": 30,
"description": "Vehicle identification number; the same as `vin`."
},
"registration_plate": {
"type": "string",
"maxLength": 30,
"description": "Registration plate; the same as `registration_plate`."
},
"hsn": {
"type": "string",
"maxLength": 8,
"description": "German manufacturer code (HSN, field 2.1 of the registration document). Looked up with `tsn` in the Kraftfahrt-Bundesamt type snapshot."
},
"tsn": {
"type": "string",
"maxLength": 8,
"description": "The first three characters of the German type code (TSN, field 2.2). Looked up with `hsn`."
},
"original_market": {
"type": "string",
"maxLength": 10,
"description": "The car's original sales market (ISO 3166-1 alpha-2), only when you know it independently. Used when a VIN is decoded."
},
"production_year": {
"type": "integer",
"description": "Read-only part of a returned Vehicle. Ignored."
}
}
},
"listing": {
"type": "object",
"additionalProperties": false,
"description": "Canonical facts about this particular car: `mileage`, `colour.name` for `color`, `condition.grade` for `condition`, `drive_side` and `flags`.",
"properties": {
"mileage": {
"type": "object",
"additionalProperties": false,
"required": [
"value",
"unit"
],
"description": "Odometer reading; the same as `mileage`.",
"properties": {
"value": {
"type": "number",
"minimum": 0,
"maximum": 10000000,
"description": "Non-negative odometer reading in the accompanying unit."
},
"unit": {
"type": "string",
"enum": [
"km",
"mi",
"mil"
],
"description": "Odometer unit: km, mi or mil (Scandinavian mile, 10 km)."
},
"read_on": {
"type": "string",
"format": "date",
"description": "Read-only date of a register's reading. Ignored. A register's past inspection reading is not today's mileage: replace it before you value the car."
}
}
},
"colour": {
"type": "object",
"additionalProperties": false,
"required": [
"name"
],
"description": "Exterior colour.",
"properties": {
"name": {
"type": "string",
"maxLength": 200,
"description": "Colour from your source; the same as `color`."
},
"family": {
"type": "string",
"maxLength": 100,
"description": "Read-only part of a returned Vehicle. Accepted and ignored."
}
}
},
"condition": {
"type": "object",
"additionalProperties": false,
"required": [
"grade"
],
"description": "Condition.",
"properties": {
"grade": {
"type": "number",
"minimum": 0,
"maximum": 4,
"description": "Condition grade from 0 through 4; the same as `condition`."
}
}
},
"drive_side": {
"type": "string",
"enum": [
"left",
"right"
],
"description": "Steering wheel position; the same as `drive_side`."
},
"flags": {
"type": "object",
"maxProperties": 30,
"additionalProperties": {
"type": "boolean"
},
"description": "Boolean risk and eligibility attributes; the same keys and effect as `flags`."
}
}
},
"object": {
"type": "string",
"description": "Read-only part of a returned Vehicle. Accepted and ignored."
},
"status": {
"type": "string",
"description": "Read-only part of a returned Vehicle. Accepted and ignored."
},
"catalogue_version": {
"type": "string",
"description": "Read-only part of a returned Vehicle. Accepted and ignored."
},
"fields": {
"type": "object",
"description": "Read-only part of a returned Vehicle. Accepted and ignored."
},
"candidates": {
"type": "object",
"description": "Read-only part of a returned Vehicle. Accepted and ignored."
}
}
}VehicleInputRef
{
"type": "object",
"additionalProperties": false,
"minProperties": 1,
"description": "An identity level as input. A level of a returned Vehicle can be sent back as it is.",
"properties": {
"id": {
"type": [
"string",
"null"
],
"maxLength": 100,
"description": "Catalogue ID from the catalogue API or a returned Vehicle. Wins over `name`. All IDs must describe one consistent catalogue hierarchy."
},
"name": {
"type": "string",
"maxLength": 200,
"description": "Name as your source spells it. Used for `brand` and `model` when there is no `id`; ignored at the other levels."
},
"from_year": {
"type": "integer",
"description": "Read-only part of a returned generation. Ignored."
},
"to_year": {
"type": "integer",
"description": "Read-only part of a returned generation. Ignored."
}
}
}ValuationResponse
{
"type": "object",
"properties": {
"request_id": {
"type": "string",
"pattern": "^(val|stf)_[A-Za-z0-9]+$"
},
"object": {
"const": "valuation"
},
"status": {
"type": "string",
"enum": [
"valued",
"refused",
"failed"
]
},
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$"
},
"mode": {
"type": "string",
"enum": [
"live",
"test"
]
},
"vehicle": {
"$ref": "#/components/schemas/Vehicle",
"description": "The vehicle the valuation used, identified against the AutoUncle catalogue, as an AVS vehicle document; provenance per value is in `identification.fields`. Present when `status` is `valued` and the vehicle is identified to a brand and a model."
},
"identification": {
"$ref": "#/components/schemas/VehicleIdentification",
"description": "How the vehicle was identified: status, depth, candidates and the provenance of every value in `vehicle`."
},
"valuation": {
"type": "object",
"properties": {
"price": {
"type": "number",
"exclusiveMinimum": 0
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"price_basis": {
"type": "string",
"enum": [
"dealer_retail",
"private_sale"
]
},
"price_basis_description": {
"type": "string",
"minLength": 1
},
"intervals": {
"type": "array",
"items": {
"type": "object",
"properties": {
"coverage": {
"type": "number",
"exclusiveMinimum": 0,
"exclusiveMaximum": 1
},
"low": {
"type": "number",
"exclusiveMinimum": 0
},
"high": {
"type": "number",
"exclusiveMinimum": 0
},
"method": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false,
"required": [
"coverage",
"low",
"high",
"method"
]
},
"minItems": 1
},
"valuation_date": {
"type": "string",
"format": "date"
}
},
"additionalProperties": false,
"required": [
"price",
"currency",
"price_basis",
"price_basis_description",
"intervals",
"valuation_date"
]
},
"precision": {
"type": "object",
"properties": {
"grade": {
"type": "string",
"enum": [
"high",
"medium",
"low",
"indicative"
]
},
"summary": {
"type": "string",
"minLength": 1
},
"identity_level": {
"type": "string"
},
"interval_width_pct": {
"type": [
"number",
"null"
],
"minimum": 0
},
"data_support": {
"type": "object",
"additionalProperties": {
"type": "integer",
"minimum": 0
}
},
"typical_error_pct": {
"type": [
"number",
"null"
],
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"grade",
"summary",
"identity_level",
"interval_width_pct",
"data_support",
"typical_error_pct"
]
},
"price_ratings": {
"type": "object",
"properties": {
"bands": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rating": {
"type": "integer",
"minimum": 1,
"maximum": 5
},
"label": {
"type": "string",
"minLength": 1
},
"from": {
"type": "number",
"minimum": 0
},
"to": {
"type": "number",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"rating",
"label",
"from",
"to"
]
},
"minItems": 5,
"maxItems": 5
},
"asking_price_rating": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 5
},
"asking_price_label": {
"type": [
"string",
"null"
]
},
"stable_within_80pct_interval": {
"type": [
"boolean",
"null"
]
}
},
"additionalProperties": false,
"required": [
"bands",
"asking_price_rating",
"asking_price_label",
"stable_within_80pct_interval"
]
},
"comparables": {
"type": "object",
"description": "Comparable listings in the valuation market, as supporting evidence. Present on a `valued` result when `options.include` contains `comparables`. They are looked up after scoring and never change the valuation. At most five on sale and five recently sold, with top-level facts only; no seller details, listing text, plates, VINs, images, dates or links.",
"properties": {
"status": {
"type": "string",
"enum": [
"included",
"none_found",
"unavailable"
]
},
"unavailable_reason": {
"type": [
"string",
"null"
],
"enum": [
"market_restricted",
"temporarily_unavailable",
null
]
},
"synthetic": {
"type": "boolean"
},
"criteria": {
"type": [
"object",
"null"
],
"properties": {
"make": {
"type": "string"
},
"model": {
"type": "string"
},
"model_year": {
"type": [
"object",
"null"
],
"properties": {
"from": {
"type": [
"integer",
"null"
]
},
"to": {
"type": [
"integer",
"null"
]
}
},
"additionalProperties": false,
"required": [
"from",
"to"
]
},
"mileage": {
"type": [
"object",
"null"
],
"properties": {
"from": {
"type": [
"integer",
"null"
]
},
"to": {
"type": [
"integer",
"null"
]
},
"unit": {
"type": "string",
"enum": [
"km",
"mi",
"mil"
]
}
},
"additionalProperties": false,
"required": [
"from",
"to",
"unit"
]
},
"fuel": {
"type": [
"string",
"null"
],
"enum": [
"petrol",
"diesel",
"electric",
"hybrid",
"plug_in_hybrid_petrol",
"plug_in_hybrid_diesel",
"lpg",
"cng",
"ethanol",
"hydrogen",
null
]
},
"transmission": {
"type": [
"string",
"null"
],
"enum": [
"manual",
"automatic",
null
]
},
"body": {
"type": [
"string",
"null"
],
"enum": [
"hatchback",
"estate",
"suv",
"sedan",
"mpv",
"convertible",
"coupe",
null
]
},
"engine_size_l": {
"type": [
"number",
"null"
]
},
"sold_within_days": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": false,
"required": [
"make",
"model",
"model_year",
"mileage",
"fuel",
"transmission",
"body",
"engine_size_l",
"sold_within_days"
]
},
"on_sale": {
"type": "array",
"maxItems": 5,
"items": {
"$ref": "#/components/schemas/ComparableListing"
}
},
"recently_sold": {
"type": "array",
"maxItems": 5,
"items": {
"$ref": "#/components/schemas/ComparableListing"
}
}
},
"additionalProperties": false,
"required": [
"status",
"unavailable_reason",
"synthetic",
"criteria",
"on_sale",
"recently_sold"
]
},
"trade_in_price": {
"type": "object",
"description": "AutoUncle's estimate of a fair price for a dealer to pay when taking the vehicle in trade, with a range. Present on a `valued` result when `options.include` contains `trade_in_price`. It is an estimate, not an offer, and it relates to the vehicle's dealer retail market value whatever `pricing.price_basis` the valuation uses. Looked up after scoring; it never changes the valuation.",
"properties": {
"status": {
"type": "string",
"enum": [
"included",
"unavailable"
]
},
"unavailable_reason": {
"type": [
"string",
"null"
],
"enum": [
"market_unsupported",
"temporarily_unavailable",
null
]
},
"synthetic": {
"type": "boolean"
},
"price": {
"type": [
"integer",
"null"
],
"exclusiveMinimum": 0
},
"low": {
"type": [
"integer",
"null"
],
"exclusiveMinimum": 0
},
"high": {
"type": [
"integer",
"null"
],
"exclusiveMinimum": 0
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
}
},
"additionalProperties": false,
"required": [
"status",
"unavailable_reason",
"synthetic",
"price",
"low",
"high",
"currency"
]
},
"similar_cars_url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "Link to cars similar to the valued vehicle for sale on the market's own AutoUncle site (autouncle.<country domain>), in the market's language. Present on a `valued` result when `options.include` contains `similar_cars_link`; null when the link could not be built (a `similar_cars_link_unavailable` warning says so). Free."
},
"selling_time": {
"$ref": "#/components/schemas/SellingTime"
},
"improve_precision": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string",
"minLength": 1
},
"reason": {
"type": "string",
"minLength": 1
},
"expected_impact": {
"type": "string",
"enum": [
"high",
"medium",
"low"
]
},
"message": {
"type": "string",
"minLength": 1
},
"candidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"name": {
"type": "string",
"minLength": 1
},
"source": {
"type": "string",
"enum": [
"provided",
"catalogue_id",
"catalogue_derived",
"text_parser",
"registry",
"catalogue_match",
"ai_text",
"ai_vision",
"imputed",
"default"
]
},
"basis": {
"type": "string",
"enum": [
"observed",
"extracted",
"catalogue",
"assumed"
],
"description": "How the value was established: observed (supplied by the caller or read from a registry record), extracted (parsed or automatically interpreted from supplied text or photos), catalogue (deterministically derived from or matched against the AutoUncle catalogue) or assumed (a heuristic default or fixed baseline, not evidence about this vehicle)."
},
"match_score": {
"type": "number"
},
"ambiguous": {
"type": "boolean"
},
"candidate_count": {
"type": "integer",
"minimum": 2
}
},
"additionalProperties": false,
"required": [
"id",
"name",
"source"
]
}
}
},
"additionalProperties": false,
"required": [
"field",
"reason",
"expected_impact",
"message"
]
}
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$"
},
"message": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false,
"required": [
"code",
"message"
]
}
},
"model": {
"type": "object",
"properties": {
"model_id": {
"type": "string",
"minLength": 1
},
"trained_on": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"catalogue_version": {
"type": [
"string",
"null"
]
},
"synthetic": {
"type": "boolean"
}
},
"additionalProperties": false,
"required": [
"model_id",
"trained_on",
"catalogue_version",
"synthetic"
]
},
"usage": {
"type": "object",
"properties": {
"billable": {
"type": "boolean"
},
"credits_used": {
"type": "integer",
"minimum": 0,
"maximum": 4
},
"original_credits_used": {
"type": "integer",
"minimum": 0,
"maximum": 4
},
"charges": {
"type": "object",
"properties": {
"base": {
"type": "integer",
"minimum": 1
},
"comparables": {
"type": "integer",
"minimum": 1
},
"images": {
"type": "integer",
"minimum": 1
},
"selling_time": {
"type": "integer",
"minimum": 1
},
"trade_in_price": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": false
},
"credits_remaining": {
"type": "integer",
"minimum": 0
},
"cache_hit": {
"type": "boolean"
},
"idempotent_replay": {
"type": "boolean"
},
"mode": {
"type": "string",
"enum": [
"live",
"test"
]
}
},
"additionalProperties": false,
"required": [
"billable",
"credits_used",
"original_credits_used",
"charges",
"credits_remaining",
"cache_hit",
"idempotent_replay",
"mode"
]
},
"error": {
"$ref": "#/components/schemas/Problem"
},
"notes": {
"$ref": "#/components/schemas/Notes"
},
"attributions": {
"$ref": "#/components/schemas/Attributions"
}
},
"additionalProperties": false,
"required": [
"request_id",
"object",
"status",
"country",
"mode",
"notes",
"attributions"
],
"allOf": [
{
"if": {
"properties": {
"status": {
"const": "valued"
}
}
},
"then": {
"required": [
"identification",
"valuation",
"precision",
"price_ratings",
"improve_precision",
"warnings",
"model"
],
"not": {
"required": [
"error"
]
}
},
"else": {
"required": [
"error"
],
"not": {
"required": [
"valuation"
]
}
}
},
{
"if": {
"properties": {
"mode": {
"const": "test"
},
"status": {
"const": "valued"
}
},
"required": [
"mode",
"status"
]
},
"then": {
"properties": {
"precision": {
"properties": {
"grade": {
"const": "indicative"
}
}
},
"model": {
"properties": {
"synthetic": {
"const": true
}
}
},
"usage": {
"properties": {
"billable": {
"const": false
},
"credits_used": {
"const": 0
}
}
}
}
}
}
]
}ComparableListing
{
"type": "object",
"properties": {
"make": {
"type": "string",
"minLength": 1
},
"model": {
"type": "string",
"minLength": 1
},
"model_year": {
"type": [
"integer",
"null"
]
},
"mileage": {
"type": [
"object",
"null"
],
"properties": {
"value": {
"type": "number",
"minimum": 0
},
"unit": {
"type": "string",
"enum": [
"km",
"mi",
"mil"
]
}
},
"additionalProperties": false,
"required": [
"value",
"unit"
]
},
"asking_price": {
"type": "integer",
"exclusiveMinimum": 0
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"price_rating": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 5
},
"days_on_market": {
"type": [
"integer",
"null"
],
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"make",
"model",
"model_year",
"mileage",
"asking_price",
"currency",
"price_rating",
"days_on_market"
],
"description": "One comparable listing, top-level facts only: make, model, model year, rounded mileage, rounded asking price, AutoUncle price rating and days on market. Nothing that identifies the listing, its seller or its page."
}NormalizationRequest
{
"type": "object",
"properties": {
"country": {
"type": "string",
"maxLength": 10,
"minLength": 2,
"description": "Market as an ISO 3166-1 alpha-2 code, such as DK, DE or GB. The market selects its own catalogue scope and mileage conventions."
},
"vehicle": {
"$ref": "#/components/schemas/VehicleInput",
"description": "The vehicle, as a VehicleInput: an AVS vehicle document (any `vehicle` an endpoint returned, posted back unchanged) or the vehicle's attributes as a listing gives them."
},
"description": {
"type": "string",
"maxLength": 20000,
"minLength": 1,
"description": "Unstructured listing text describing the vehicle. Existing parsers and deployment-configured optional AI can propose attributes; the response identifies assumptions and unresolved inputs."
},
"images": {
"type": "array",
"minItems": 1,
"maxItems": 8,
"items": {
"type": "object",
"properties": {
"url": {
"type": "string",
"maxLength": 2048,
"format": "uri",
"description": "Public HTTPS image URL on port 443, without credentials or fragments. Private network destinations and redirects are rejected. Remote images must be supported image types and at most 8 MB each."
},
"data": {
"type": "string",
"maxLength": 1000000,
"description": "Strict base64-encoded image bytes, without a data-URL prefix. Inline data must also fit the total 1 MB API request limit."
},
"media_type": {
"type": "string",
"maxLength": 100,
"description": "MIME type for inline image bytes: image/jpeg, image/png, image/webp or image/gif. The actual image signature is checked."
}
},
"additionalProperties": false,
"anyOf": [
{
"required": [
"url"
]
},
{
"required": [
"data",
"media_type"
]
}
]
},
"description": "Up to eight vehicle photos, each supplied by HTTPS URL or inline base64 data. AI image resolution is deployment-configured and never runs for test keys. Warnings identify unused images. On a live key, photos cost one extra credit per request (not per photo), charged only when the request succeeds and a value was read from them (`usage.charges.images`); skipped or unused photos are not charged."
},
"options": {
"type": "object",
"properties": {
"resolution": {
"type": "string",
"maxLength": 200,
"enum": [
"auto",
"no_ai",
"strict"
],
"description": "auto uses deterministic resolution and optional configured AI; no_ai and strict use deterministic resolution only. Normalization never assumes a year or mileage. Strict resolution also ignores allow_equipment_estimation."
},
"allow_equipment_estimation": {
"type": "boolean",
"default": false,
"description": "Explicitly allow equipment the request does not state to be assumed: the catalogue's equipment for the identified trim when the catalogue lists it, otherwise the equipment at least 70% of comparable vehicles on the market have. Assumed equipment is only added, never against equipment the request, its description or its photos state or deny, and is marked source imputed, basis assumed in identification.fields (availability unknown in vehicle.equipment), with an equipment_assumed warning and an improve_precision hint. Test keys use only the catalogue trim, never market data. Default false. Strict resolution ignores it."
}
},
"additionalProperties": false,
"description": "How the vehicle is resolved."
}
},
"additionalProperties": false,
"required": [
"country"
],
"anyOf": [
{
"required": [
"vehicle"
],
"properties": {
"vehicle": {
"minProperties": 1
}
}
},
{
"required": [
"description"
]
},
{
"required": [
"images"
]
}
],
"description": "A normalization request for one market. It accepts the same vehicle (a VehicleInput, including a Vehicle returned by any endpoint), description and images as a valuation request. Nothing is valued and no year or mileage is assumed."
}NormalizationResponse
{
"type": "object",
"properties": {
"request_id": {
"type": "string",
"pattern": "^nrm_[A-Za-z0-9]+$",
"description": "The normalization's request ID, shown in the console request log."
},
"object": {
"type": "string",
"enum": [
"normalization"
]
},
"status": {
"type": "string",
"enum": [
"normalized"
]
},
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$"
},
"mode": {
"type": "string",
"enum": [
"live",
"test"
]
},
"ambiguous": {
"type": "boolean",
"description": "True when several catalogue records fit (identification.status is ambiguous); see identification.candidates."
},
"vehicle": {
"$ref": "#/components/schemas/Vehicle",
"description": "The identified vehicle. An AVS vehicle document; left out when the vehicle could not be identified to a brand and a model, with the reason in `identification`."
},
"identification": {
"$ref": "#/components/schemas/VehicleIdentification",
"description": "How the vehicle was identified: status, depth, candidates and the provenance of every value in `vehicle`."
},
"improve_precision": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string",
"minLength": 1
},
"reason": {
"type": "string",
"minLength": 1
},
"expected_impact": {
"type": "string",
"enum": [
"high",
"medium",
"low"
]
},
"message": {
"type": "string",
"minLength": 1
},
"candidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"name": {
"type": "string",
"minLength": 1
},
"source": {
"type": "string",
"enum": [
"provided",
"catalogue_id",
"catalogue_derived",
"text_parser",
"registry",
"catalogue_match",
"ai_text",
"ai_vision",
"imputed",
"default"
]
},
"basis": {
"type": "string",
"enum": [
"observed",
"extracted",
"catalogue",
"assumed"
],
"description": "How the value was established: observed (supplied by the caller or read from a registry record), extracted (parsed or automatically interpreted from supplied text or photos), catalogue (deterministically derived from or matched against the AutoUncle catalogue) or assumed (a heuristic default or fixed baseline, not evidence about this vehicle)."
},
"match_score": {
"type": "number"
},
"ambiguous": {
"type": "boolean"
},
"candidate_count": {
"type": "integer",
"minimum": 2
}
},
"additionalProperties": false,
"required": [
"id",
"name",
"source"
]
}
}
},
"additionalProperties": false,
"required": [
"field",
"reason",
"expected_impact",
"message"
]
}
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$"
},
"message": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false,
"required": [
"code",
"message"
]
}
},
"usage": {
"type": "object",
"properties": {
"billable": {
"type": "boolean"
},
"credits_used": {
"type": "integer",
"minimum": 0,
"maximum": 2
},
"original_credits_used": {
"type": "integer",
"minimum": 0,
"maximum": 2
},
"charges": {
"type": "object",
"properties": {
"base": {
"type": "integer",
"minimum": 1
},
"images": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": false
},
"credits_remaining": {
"type": "integer",
"minimum": 0
},
"cache_hit": {
"type": "boolean"
},
"idempotent_replay": {
"type": "boolean"
},
"mode": {
"type": "string",
"enum": [
"live",
"test"
]
}
},
"additionalProperties": false,
"required": [
"billable",
"credits_used",
"original_credits_used",
"charges",
"credits_remaining",
"cache_hit",
"idempotent_replay",
"mode"
]
},
"notes": {
"$ref": "#/components/schemas/Notes"
},
"attributions": {
"$ref": "#/components/schemas/Attributions"
}
},
"additionalProperties": false,
"required": [
"request_id",
"object",
"status",
"country",
"mode",
"ambiguous",
"identification",
"improve_precision",
"warnings",
"usage",
"notes",
"attributions"
],
"description": "A normalized vehicle with its provenance, any candidates, hints, warnings, usage and the common notes and attributions."
}Vehicle
{
"description": "The vehicle as an AutoUncle Vehicle Schema (AVS) 0.3 `vehicle` document: https://github.com/AutoUncle/avs. Only `avs` and `identity` (brand and model) are always present; anything not known is left out, never null or empty. A missing equipment feature means unknown, not absent. Catalogue records carry their AutoUncle ID as `ids[{scheme: \"autouncle\"}]`; AutoUncle's generation, which includes the body, is `identity.body`, and its equipment variant is `equipment.trim`. Facts AVS has no field for yet are in `extensions[\"com.autouncle\"]`: `battery_kwh` (gross or usable not known), `electric_range_km` (test cycle not known), `doors` above 6, `seats` above 9, `production_year`, `first_registration` without a full date, `hsn`, `tsn`, `condition_grade` (0 to 4) and `variant_text` (the variant text the vehicle was described with, as given). Validate it with the AVS packages, or post it back unchanged as a request's `vehicle`.",
"allOf": [
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://schema.autouncle.com/avs/0.3/avs.schema.json",
"title": "AVS – AutoUncle Vehicle Schema",
"description": "Draft 0.3. AVS describes a car: the facts about it, never how they were obtained or what someone thinks it is worth. A document has up to four layers: WHAT car type it is (identity), HOW it is built (specification), WHAT it is equipped with (equipment) and, for one physical car, WHICH car it is and what has happened to it (vehicle). A car-type document (e.g. 'BMW 320e G20 Sedan M Sport') omits `vehicle`. Context such as listings, valuations, data provenance or match confidence belongs in companion schemas that reference an AVS document.",
"type": "object",
"required": [
"avs",
"identity"
],
"additionalProperties": false,
"properties": {
"avs": {
"$ref": "#/$defs/Envelope"
},
"identity": {
"$ref": "#/$defs/Identity"
},
"specification": {
"$ref": "#/$defs/Specification"
},
"equipment": {
"$ref": "#/$defs/Equipment"
},
"vehicle": {
"$ref": "#/$defs/Vehicle"
},
"extensions": {
"description": "Vendor-specific data that has no AVS field yet. Keys are reverse-DNS namespaces, e.g. `com.autouncle`, `de.mobile`.",
"type": "object",
"propertyNames": {
"pattern": "^[a-z0-9]+(\\.[a-z0-9-]+)+$"
}
}
},
"$defs": {
"Envelope": {
"description": "Document metadata.",
"type": "object",
"required": [
"version",
"kind"
],
"additionalProperties": false,
"properties": {
"version": {
"const": "0.3"
},
"kind": {
"description": "`type` = a car type as built (no physical car). `vehicle` = one physical car, so the `vehicle` block is required. Fields that only make sense for one kind are rejected in the other.",
"enum": [
"type",
"vehicle"
]
},
"id": {
"description": "Stable id of this document, if the producer has one.",
"type": "string"
},
"locale": {
"description": "Language of free-text names (BCP 47).",
"type": "string",
"examples": [
"da-DK"
]
}
}
},
"Identity": {
"description": "Where the car sits in the catalogue: brand → series → model → generation → phase → body → drivetrain, plus the configuration that pairs a body with a drivetrain. Generation, body and drivetrain are independent facts: one drivetrain is shared by every body it was sold in. Only brand and model are required; levels that are not known are left out.",
"type": "object",
"required": [
"brand",
"model"
],
"additionalProperties": false,
"properties": {
"brand": {
"$ref": "#/$defs/CatalogueRef",
"unevaluatedProperties": false
},
"series": {
"$ref": "#/$defs/CatalogueRef",
"description": "Optional brand grouping, e.g. BMW 'i'.",
"unevaluatedProperties": false
},
"model": {
"$ref": "#/$defs/CatalogueRef",
"unevaluatedProperties": false
},
"generation": {
"description": "A generation of the model, e.g. 'Golf VII' or 'G20/G21', with an envelope year range covering all its bodies. Holds no body or engine data.",
"allOf": [
{
"$ref": "#/$defs/CatalogueRef"
}
],
"properties": {
"code": {
"description": "Manufacturer chassis/generation code.",
"type": "string",
"examples": [
"G20",
"Mk7",
"W206"
]
},
"fromYear": {
"type": "integer",
"minimum": 1940
},
"toYear": {
"type": [
"integer",
"null"
],
"minimum": 1940,
"description": "null = still in production."
}
},
"unevaluatedProperties": false
},
"phase": {
"description": "Production phase within the generation: the launch version or a facelift (BMW 'LCI', Mercedes 'Mopf'). Facelifts change looks, equipment and often engines, and they move prices, so they get their own level instead of being a new generation.",
"allOf": [
{
"$ref": "#/$defs/CatalogueRef"
}
],
"properties": {
"kind": {
"enum": [
"launch",
"facelift"
]
},
"index": {
"description": "0 = launch, 1 = first facelift, …",
"type": "integer",
"minimum": 0
},
"fromYear": {
"type": "integer",
"minimum": 1940
},
"toYear": {
"type": [
"integer",
"null"
],
"minimum": 1940
}
},
"unevaluatedProperties": false
},
"body": {
"description": "One body style of the generation with its own production years, e.g. 'Golf VII Variant' or 'Transporter T6 Panel Van L2H1'. Everything that is about the shell lives here: type, doors, length, roof, cab.",
"allOf": [
{
"$ref": "#/$defs/CatalogueRef"
}
],
"properties": {
"type": {
"$ref": "#/$defs/BodyType"
},
"doors": {
"type": "integer",
"minimum": 1,
"maximum": 6
},
"oemName": {
"description": "The manufacturer's own body name.",
"type": "string",
"examples": [
"Touring",
"Variant",
"Sportback",
"Shooting Brake"
]
},
"lengthClass": {
"description": "Van/MPV length with OEM token.",
"type": "string",
"examples": [
"L1",
"L2",
"L3"
]
},
"roofClass": {
"description": "Van roof height with OEM token.",
"type": "string",
"examples": [
"H1",
"H2"
]
},
"cabType": {
"type": "string",
"examples": [
"single",
"double",
"extended"
]
},
"vanBody": {
"enum": [
"panel_van",
"kombi",
"crew_van",
"bus",
"chassis_cab"
]
},
"fromYear": {
"type": "integer",
"minimum": 1940
},
"toYear": {
"type": [
"integer",
"null"
],
"minimum": 1940
}
},
"unevaluatedProperties": false
},
"drivetrain": {
"description": "One technical spec (engine code, energy, displacement, power, torque, gearbox, gears, traction, battery, emission standard), shared by every body it was sold in. Two drivetrains differ only if the spec differs, so name tokens (OPF, ACT), trims and seats never create a new one.",
"$ref": "#/$defs/CatalogueRef",
"unevaluatedProperties": false
},
"configuration": {
"description": "The pairing of this body with this drivetrain as it was actually sold. It is the most precise car-type identity and owns what depends on both: seat count, official consumption, CO2 and electric range.",
"allOf": [
{
"$ref": "#/$defs/CatalogueRef"
}
],
"properties": {
"seats": {
"type": "integer",
"minimum": 1,
"maximum": 9
}
},
"unevaluatedProperties": false
},
"typeApproval": {
"description": "The official EU identity of the car type (Reg. 2018/858, printed on the Certificate of Conformity and carried in national registers). Type/Variant/Version (TVV) is legal-centric, not trim-centric, so it sits beside the catalogue hierarchy rather than replacing it.",
"type": "object",
"additionalProperties": false,
"properties": {
"number": {
"type": "string",
"examples": [
"e1*2007/46*1832*12"
]
},
"type": {
"type": "string"
},
"variant": {
"type": "string"
},
"version": {
"type": "string"
},
"category": {
"description": "UNECE vehicle category.",
"type": "string",
"examples": [
"M1",
"N1"
]
}
}
}
}
},
"CatalogueRef": {
"description": "A catalogue record: its name and its identifiers in any code systems. Left open so that levels can extend it; every place that uses it closes it with `unevaluatedProperties: false`, so unknown keys are rejected.",
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"description": "Canonical name.",
"type": "string"
},
"ids": {
"description": "The record's current identifiers: at most one per scheme and country. Former identifiers (from a merge or rename) are not listed; the code system keeps resolving them to the current one. No scheme is privileged: AutoUncle's own catalogue is the `autouncle` scheme like any other. Two references describe the same record when they share an identifier, meaning the same scheme, value and country. JSON Schema cannot enforce one-per-scheme, so producers must.",
"type": "array",
"items": {
"$ref": "#/$defs/Id"
},
"minItems": 1,
"uniqueItems": true
},
"localNames": {
"description": "Market-specific names, keyed by ISO 3166-1 alpha-2 country.",
"type": "object",
"propertyNames": {
"pattern": "^[A-Z]{2}$"
},
"additionalProperties": {
"type": "string"
}
}
}
},
"Id": {
"type": "object",
"required": [
"scheme",
"value"
],
"additionalProperties": false,
"properties": {
"scheme": {
"description": "The code system, as a lowercase, hyphenated name. Open list; see docs/id-schemes.md for registered schemes and which level each identifies. `autouncle` is AutoUncle's catalogue.",
"type": "string",
"pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
"examples": [
"autouncle",
"wikidata",
"kba-hsn-tsn",
"type-approval",
"jato",
"dat-europa-code",
"schwacke",
"eurotax",
"cap-hpi",
"tecdoc-ktype",
"nhtsa-vpic"
]
},
"value": {
"description": "The identifier, exactly as the code system writes it.",
"type": "string",
"minLength": 1
},
"country": {
"description": "The country the value is valid in. Required for national and per-market schemes, not allowed for global ones (see docs/id-schemes.md).",
"type": "string",
"pattern": "^[A-Z]{2}$"
}
},
"description": "One identifier of a catalogue record in one code system. The key is scheme + value + country: an omitted country is part of the key, not a wildcard. Registered schemes (docs/id-schemes.md) fix whether country is required, which value it must have, and sometimes the value's format.",
"allOf": [
{
"if": {
"properties": {
"scheme": {
"const": "kba-hsn-tsn"
}
},
"required": [
"scheme"
]
},
"then": {
"required": [
"country"
],
"properties": {
"country": {
"const": "DE"
},
"value": {
"pattern": "^[0-9]{4}/[0-9A-Z]{3}$"
}
}
}
},
{
"if": {
"properties": {
"scheme": {
"const": "schwacke"
}
},
"required": [
"scheme"
]
},
"then": {
"required": [
"country"
],
"properties": {
"country": {
"const": "DE"
}
}
}
},
{
"if": {
"properties": {
"scheme": {
"const": "cap-hpi"
}
},
"required": [
"scheme"
]
},
"then": {
"required": [
"country"
],
"properties": {
"country": {
"const": "GB"
}
}
}
},
{
"if": {
"properties": {
"scheme": {
"const": "nhtsa-vpic"
}
},
"required": [
"scheme"
]
},
"then": {
"required": [
"country"
],
"properties": {
"country": {
"const": "US"
}
}
}
},
{
"if": {
"properties": {
"scheme": {
"enum": [
"jato",
"eurotax"
]
}
},
"required": [
"scheme"
]
},
"then": {
"required": [
"country"
]
}
},
{
"if": {
"properties": {
"scheme": {
"enum": [
"autouncle",
"wikidata",
"type-approval",
"dat-europa-code",
"tecdoc-ktype"
]
}
},
"required": [
"scheme"
]
},
"then": {
"properties": {
"country": false
}
}
},
{
"if": {
"properties": {
"scheme": {
"const": "wikidata"
}
},
"required": [
"scheme"
]
},
"then": {
"properties": {
"value": {
"pattern": "^Q[1-9][0-9]*$"
}
}
}
}
]
},
"Specification": {
"description": "Technical facts about the car type. Units are always in the field name (kW, Nm, mm, kg, kWh, g/km) so there is never a unit field to look up.",
"type": "object",
"additionalProperties": false,
"properties": {
"body": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"$ref": "#/$defs/BodyType"
},
"doors": {
"type": "integer",
"minimum": 1,
"maximum": 6
},
"seats": {
"description": "Seat count of this configuration. An optional extra seat row is equipment.",
"type": "integer",
"minimum": 1,
"maximum": 9
},
"driveSide": {
"enum": [
"left",
"right"
]
}
}
},
"powertrain": {
"$ref": "#/$defs/Powertrain"
},
"battery": {
"$ref": "#/$defs/Battery"
},
"performance": {
"type": "object",
"additionalProperties": false,
"properties": {
"zeroTo100KmhS": {
"type": "number",
"minimum": 0
},
"topSpeedKmh": {
"type": "integer",
"minimum": 0
}
}
},
"efficiency": {
"description": "Official consumption/emissions under one test cycle. Repeat the block when a car has several (e.g. NEDC and WLTP). Values belong to the body + drivetrain pairing (an estate burns more than the sedan with the same engine) and fall back to the drivetrain's value.",
"type": "array",
"items": {
"$ref": "#/$defs/Efficiency"
}
},
"realWorldRange": {
"description": "Measured or modelled real-world EV range, as opposed to the official cycle value.",
"type": "object",
"additionalProperties": false,
"properties": {
"cityKm": {
"type": "integer"
},
"highwayKm": {
"type": "integer"
},
"combinedKm": {
"type": "integer"
}
}
},
"emissionStandard": {
"type": "string",
"examples": [
"Euro 6d",
"Euro 6d-TEMP",
"Euro 7"
]
},
"dimensions": {
"type": "object",
"additionalProperties": false,
"properties": {
"lengthMm": {
"type": "integer"
},
"widthMm": {
"type": "integer"
},
"heightMm": {
"type": "integer"
},
"wheelbaseMm": {
"type": "integer"
},
"bootLitres": {
"type": "integer"
},
"groundClearanceMm": {
"type": "integer"
},
"turningCircleM": {
"type": "number"
},
"bootMaxLitres": {
"type": "integer",
"description": "Rear seats folded."
},
"frunkLitres": {
"type": "integer"
},
"fuelTankLitres": {
"type": "integer"
}
}
},
"weights": {
"type": "object",
"additionalProperties": false,
"properties": {
"kerbKg": {
"type": "integer"
},
"grossKg": {
"type": "integer"
},
"towingBrakedKg": {
"type": "integer"
},
"payloadKg": {
"type": "integer"
},
"towingUnbrakedKg": {
"type": "integer"
},
"roofLoadKg": {
"type": "integer"
}
}
},
"wheels": {
"type": "object",
"additionalProperties": false,
"properties": {
"rimSizeInch": {
"type": "number"
},
"tyresFront": {
"type": "string",
"examples": [
"225/45 R18"
]
},
"tyresRear": {
"type": "string",
"examples": [
"255/40 R18"
]
},
"spare": {
"enum": [
"full_size",
"space_saver",
"repair_kit",
"run_flat",
"none"
]
}
}
},
"charging": {
"description": "How an electrified car is charged.",
"type": "object",
"additionalProperties": false,
"properties": {
"ports": {
"type": "array",
"items": {
"enum": [
"type1",
"type2",
"ccs1",
"ccs2",
"chademo",
"nacs",
"gbt",
"schuko"
]
}
},
"maxAcKw": {
"type": "number"
},
"maxDcKw": {
"type": "number"
},
"dc10To80Min": {
"type": "number"
},
"bidirectional": {
"enum": [
"none",
"v2l",
"v2h",
"v2g"
]
}
}
},
"safety": {
"type": "object",
"additionalProperties": false,
"properties": {
"euroNcapStars": {
"type": "integer",
"minimum": 0,
"maximum": 5
},
"euroNcapYear": {
"type": "integer"
},
"airbags": {
"type": "integer",
"minimum": 0
}
}
},
"environmentalLabels": {
"description": "National emission labels the car type qualifies for.",
"type": "array",
"items": {
"type": "object",
"required": [
"scheme",
"value"
],
"additionalProperties": false,
"properties": {
"scheme": {
"type": "string",
"examples": [
"de-umweltplakette",
"fr-critair",
"es-dgt",
"eu-co2-class"
]
},
"value": {
"type": "string",
"examples": [
"4 (green)",
"1",
"ECO",
"B"
]
}
}
}
},
"segment": {
"description": "Market segment(s), e.g. Compact, SUV.",
"type": "array",
"items": {
"$ref": "#/$defs/CatalogueRef",
"unevaluatedProperties": false
}
}
}
},
"Powertrain": {
"description": "How the car is propelled. Fuel is split into two independent questions: what does it burn (`energy`) and how electrified is it (`electrification`). Combined tokens like 'petrol hybrid' are never needed.",
"type": "object",
"additionalProperties": false,
"properties": {
"energy": {
"description": "Energy carriers the car can use, primary first. A bi-fuel LPG car is [\"petrol\", \"lpg\"]; a BEV is [\"electricity\"].",
"type": "array",
"minItems": 1,
"items": {
"enum": [
"petrol",
"diesel",
"electricity",
"hydrogen",
"cng",
"lpg",
"ethanol",
"other"
]
}
},
"electrification": {
"description": "none = pure combustion, mhev = 48V mild, fhev = full self-charging hybrid, phev = plug-in, erev = range extender, bev = battery electric, fcev = fuel cell.",
"enum": [
"none",
"mhev",
"fhev",
"phev",
"erev",
"bev",
"fcev"
]
},
"engine": {
"type": "object",
"additionalProperties": false,
"properties": {
"code": {
"type": "string",
"examples": [
"B48B20"
]
},
"displacementCc": {
"type": "integer",
"minimum": 0
},
"cylinders": {
"type": "integer",
"minimum": 0
},
"aspiration": {
"enum": [
"natural",
"turbo",
"supercharged",
"twin_turbo"
]
}
}
},
"electricMotors": {
"type": "object",
"additionalProperties": false,
"properties": {
"count": {
"type": "integer",
"minimum": 0
},
"powerKw": {
"type": "number",
"description": "Combined motor power."
}
}
},
"powerKw": {
"description": "Total system power.",
"type": "number",
"minimum": 0
},
"powerHp": {
"description": "Metric horsepower (PS/hk), derived from kW; provided for display.",
"type": "number",
"minimum": 0
},
"torqueNm": {
"type": "number",
"minimum": 0
},
"transmission": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"enum": [
"manual",
"automatic",
"dct",
"cvt",
"single_speed"
]
},
"gears": {
"type": "integer",
"minimum": 1
},
"tradeName": {
"type": "string",
"examples": [
"Steptronic",
"S tronic",
"DSG"
]
}
}
},
"traction": {
"description": "Driven wheels. `2wd` = two-wheel drive where the driven axle is not known, e.g. from a register that records only the number of driven axles; use `fwd` or `rwd` when it is known.",
"enum": [
"fwd",
"rwd",
"2wd",
"awd"
]
},
"awdType": {
"description": "Only for awd.",
"enum": [
"permanent",
"on_demand",
"electric_axle"
]
}
}
},
"Battery": {
"description": "Traction battery (BEV/PHEV/FHEV). Fields chosen to line up with the EU Battery Passport.",
"type": "object",
"additionalProperties": false,
"properties": {
"grossKwh": {
"type": "number",
"minimum": 0
},
"netKwh": {
"type": "number",
"minimum": 0
},
"chemistry": {
"type": "string",
"examples": [
"NMC",
"LFP",
"NCA"
]
},
"voltageV": {
"type": "integer",
"examples": [
400,
800
]
},
"heatPump": {
"enum": [
"standard",
"optional",
"unavailable"
]
},
"passportId": {
"description": "Vehicle documents only: EU Battery Passport identifier/URI (Reg. 2023/1542).",
"type": "string"
}
}
},
"Efficiency": {
"type": "object",
"required": [
"cycle"
],
"additionalProperties": false,
"properties": {
"cycle": {
"enum": [
"WLTP",
"NEDC",
"NEDC_WLTP_EQUIVALENT",
"EPA",
"CLTC",
"WLTC"
]
},
"fuelL100km": {
"type": "object",
"additionalProperties": false,
"properties": {
"combined": {
"type": "number"
},
"urban": {
"type": "number"
},
"extraUrban": {
"type": "number"
}
}
},
"electricKwh100km": {
"type": "number"
},
"electricRangeKm": {
"type": "integer"
},
"co2GKm": {
"type": "integer"
}
}
},
"Equipment": {
"description": "What the car is equipped with. A trim, package or option is identified by its NAME; that is what buyers, adverts and valuation use, and a name alone is enough to price it. Its contents are described separately as `features`. Absence is only known when stated (`fitted: false` / `availability: absent`); a missing entry means unknown.",
"type": "object",
"additionalProperties": false,
"properties": {
"trim": {
"description": "The ONE base trim the car was bought in, e.g. 'Carrera 4S', 'Luxury Line', 'M Sport'. Never contains a body word: 'Carrera 4S Cabriolet' is trim 'Carrera 4S' on body 'Cabriolet'.",
"$ref": "#/$defs/EquipmentRef"
},
"packages": {
"description": "Named add-on packages, e.g. 'Sport Chrono', 'AMG Line', 'Winter Package'.",
"type": "array",
"items": {
"$ref": "#/$defs/EquipmentRef"
}
},
"options": {
"description": "Individually ordered options, e.g. 'Harman Kardon Sound System'.",
"type": "array",
"items": {
"$ref": "#/$defs/EquipmentRef"
}
},
"features": {
"description": "Flat, brand-agnostic list of what the car has, so consumers can ask 'does it have adaptive cruise?' without knowing BMW calls it 'Active Cruise Control'.",
"type": "array",
"items": {
"$ref": "#/$defs/Feature"
}
}
}
},
"EquipmentRef": {
"description": "A trim, package or option by name, optionally pointing to its catalogue record.",
"allOf": [
{
"$ref": "#/$defs/CatalogueRef"
}
],
"properties": {
"variations": {
"description": "Type documents only: other ways the name is written, used for matching ('C4S' = 'Carrera 4S').",
"type": "array",
"items": {
"type": "string"
}
},
"drivetrains": {
"description": "Type documents only, trims: the drivetrains this trim is sold with.",
"type": "array",
"items": {
"$ref": "#/$defs/CatalogueRef",
"unevaluatedProperties": false
}
},
"fitted": {
"description": "Vehicle documents only: true = this car has it, false = known absent. Omit when unknown.",
"type": "boolean"
}
},
"unevaluatedProperties": false
},
"Feature": {
"allOf": [
{
"$ref": "#/$defs/CatalogueRef"
}
],
"required": [
"key"
],
"properties": {
"key": {
"description": "Stable machine key of the canonical feature.",
"type": "string",
"pattern": "^[A-Z0-9_]+$",
"examples": [
"SAFETY_AEB",
"DRIVE_CRUISE_CONTROL",
"LIGHTING_HEADLIGHTS_LED"
]
},
"category": {
"description": "Top-level group.",
"type": "string",
"examples": [
"SAFETY",
"DRIVE",
"INFOTAINMENT",
"LIGHTING",
"SEATS"
]
},
"brandName": {
"description": "What the brand calls it.",
"type": "string"
},
"availability": {
"description": "Type documents: standard or optional on this trim. Vehicle documents: fitted, absent or unknown on this car.",
"enum": [
"standard",
"optional",
"fitted",
"absent",
"unknown"
]
},
"viaPackage": {
"description": "Name or id of the package that brings this feature.",
"type": "string"
}
},
"unevaluatedProperties": false
},
"Vehicle": {
"description": "One physical car. Everything here can differ between two cars of the same drivetrain.",
"type": "object",
"additionalProperties": false,
"properties": {
"vin": {
"type": "string",
"pattern": "^[A-HJ-NPR-Z0-9]{17}$",
"description": "ISO 3779 VIN. Identifies one car and can be personal data when combined with an owner, so store and share it only where that is needed and allowed."
},
"registration": {
"type": "object",
"additionalProperties": false,
"properties": {
"plate": {
"type": "string",
"description": "Registration plate as issued. It can be personal data; the same care as `vin` applies, and plates are re-issued, so a plate identifies a car only at a point in time."
},
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$"
},
"firstRegistrationDate": {
"type": "string",
"format": "date"
},
"modelYear": {
"type": "integer"
},
"isImported": {
"type": "boolean",
"description": "First registered in another country than `country`."
},
"originalCountry": {
"type": "string",
"pattern": "^[A-Z]{2}$"
},
"usage": {
"description": "Registered use, when not private.",
"enum": [
"private",
"commercial",
"taxi",
"rental",
"demo",
"leasing",
"camper"
]
},
"productionDate": {
"type": "string",
"format": "date"
}
}
},
"odometer": {
"type": "object",
"required": [
"km"
],
"additionalProperties": false,
"properties": {
"km": {
"type": "integer",
"minimum": 0
},
"readAt": {
"type": "string",
"format": "date"
}
}
},
"colour": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"description": "Manufacturer paint name.",
"type": "string",
"examples": [
"Portimao Blue"
]
},
"family": {
"enum": [
"black",
"white",
"grey",
"silver",
"blue",
"red",
"green",
"brown",
"beige",
"yellow",
"orange",
"purple",
"gold",
"other"
]
},
"finish": {
"enum": [
"solid",
"metallic",
"pearl",
"matte"
]
}
}
},
"interior": {
"type": "object",
"additionalProperties": false,
"properties": {
"upholstery": {
"enum": [
"cloth",
"part_leather",
"leather",
"synthetic_leather",
"alcantara",
"other"
]
},
"colour": {
"type": "string"
},
"name": {
"type": "string",
"description": "Manufacturer name.",
"examples": [
"Vernasca Black"
]
}
}
},
"condition": {
"description": "Physical state as observed, stated as facts rather than grades.",
"type": "object",
"additionalProperties": false,
"properties": {
"damages": {
"type": "array",
"items": {
"type": "object",
"required": [
"area"
],
"additionalProperties": false,
"properties": {
"area": {
"type": "string",
"examples": [
"front_bumper",
"left_rear_door",
"windscreen",
"underbody"
]
},
"kind": {
"enum": [
"scratch",
"dent",
"crack",
"paint",
"rust",
"mechanical",
"electrical",
"hail",
"flood",
"fire"
]
},
"repaired": {
"type": "boolean"
}
}
}
},
"nonSmoker": {
"type": "boolean"
},
"keys": {
"type": "integer",
"minimum": 0
},
"modifications": {
"description": "Deviations from factory spec (tuning, conversions).",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"history": {
"type": "object",
"additionalProperties": false,
"properties": {
"previousOwners": {
"type": "integer",
"minimum": 0
},
"fullServiceHistory": {
"type": "boolean"
},
"lastServiceDate": {
"type": "string",
"format": "date"
},
"lastInspectionDate": {
"type": "string",
"format": "date",
"description": "Periodic technical inspection (syn, TÜV, MOT, APK)."
},
"nextInspectionDue": {
"type": "string",
"format": "date"
},
"accidents": {
"type": "integer",
"minimum": 0
},
"batteryStateOfHealthPct": {
"type": "number",
"minimum": 0,
"maximum": 100
},
"events": {
"description": "Dated history entries (service, inspection, owner change, damage repair, odometer reading).",
"type": "array",
"items": {
"type": "object",
"required": [
"date",
"type"
],
"additionalProperties": false,
"properties": {
"date": {
"type": "string",
"format": "date"
},
"type": {
"enum": [
"service",
"inspection",
"owner_change",
"damage",
"repair",
"odometer_reading",
"recall",
"import"
]
},
"odometerKm": {
"type": "integer"
},
"note": {
"type": "string"
}
}
}
}
}
},
"warranty": {
"type": "object",
"additionalProperties": false,
"properties": {
"factoryUntil": {
"type": "string",
"format": "date"
},
"batteryUntil": {
"type": "string",
"format": "date"
},
"dealerMonths": {
"type": "integer"
}
}
},
"originalListPrice": {
"description": "Price when new in the first-registration market, including the options fitted.",
"$ref": "#/$defs/Money"
}
}
},
"Money": {
"type": "object",
"required": [
"amount",
"currency"
],
"additionalProperties": false,
"properties": {
"amount": {
"type": "number"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "ISO 4217."
}
}
},
"BodyType": {
"description": "Coarse body style. The manufacturer's own name goes in body.oemName.",
"enum": [
"hatchback",
"sedan",
"liftback",
"estate",
"mpv",
"suv",
"coupe",
"cabriolet",
"roadster",
"pickup",
"van"
]
},
"TypeDocumentRules": {
"description": "What a `type` document may not contain: anything about one physical car.",
"properties": {
"vehicle": false,
"equipment": {
"properties": {
"trim": {
"$ref": "#/$defs/TypeEquipmentRef"
},
"packages": {
"items": {
"$ref": "#/$defs/TypeEquipmentRef"
}
},
"options": {
"items": {
"$ref": "#/$defs/TypeEquipmentRef"
}
},
"features": {
"items": {
"properties": {
"availability": {
"enum": [
"standard",
"optional"
]
}
}
}
}
}
},
"specification": {
"properties": {
"battery": {
"properties": {
"passportId": false
}
}
}
}
}
},
"VehicleDocumentRules": {
"description": "What a `vehicle` document must and may not contain: it describes one physical car, so it has a `vehicle` block and no catalogue matching data.",
"required": [
"vehicle"
],
"properties": {
"equipment": {
"properties": {
"trim": {
"$ref": "#/$defs/VehicleEquipmentRef"
},
"packages": {
"items": {
"$ref": "#/$defs/VehicleEquipmentRef"
}
},
"options": {
"items": {
"$ref": "#/$defs/VehicleEquipmentRef"
}
},
"features": {
"items": {
"properties": {
"availability": {
"enum": [
"fitted",
"absent",
"unknown"
]
}
}
}
}
}
}
}
},
"TypeEquipmentRef": {
"properties": {
"fitted": false
}
},
"VehicleEquipmentRef": {
"properties": {
"variations": false,
"drivetrains": false
}
}
},
"allOf": [
{
"if": {
"required": [
"avs"
],
"properties": {
"avs": {
"required": [
"kind"
],
"properties": {
"kind": {
"const": "type"
}
}
}
}
},
"then": {
"$ref": "#/$defs/TypeDocumentRules"
}
},
{
"if": {
"required": [
"avs"
],
"properties": {
"avs": {
"required": [
"kind"
],
"properties": {
"kind": {
"const": "vehicle"
}
}
}
}
},
"then": {
"$ref": "#/$defs/VehicleDocumentRules"
}
}
]
}
],
"properties": {
"avs": {
"properties": {
"kind": {
"const": "vehicle"
}
}
}
}
}VehicleIdentification
{
"type": "object",
"additionalProperties": false,
"required": [
"status"
],
"description": "How the vehicle was identified against the AutoUncle catalogue: what AVS has no place for. Values are left out when not known.",
"properties": {
"status": {
"type": "string",
"enum": [
"identified",
"partially_identified",
"ambiguous",
"unidentified"
],
"x-extensible-enum": true,
"description": "identified: the catalogue drivetrain is known. partially_identified: identity stops at the brand, model or generation and nothing competes. ambiguous: several catalogue records fit at some level; that level is left out of identity and listed in candidates. unidentified: the catalogue does not know the make; the vehicle carries the brand and model names as stated, without IDs."
},
"level": {
"type": "string",
"enum": [
"brand",
"model",
"generation",
"drivetrain"
],
"description": "The deepest catalogue level identified. `generation` is AutoUncle's generation-with-body, published as AVS `identity.body`."
},
"catalogue_version": {
"type": "string",
"description": "The catalogue release that identified the vehicle, as GET /v1/catalogue/version reports it."
},
"candidates": {
"type": "object",
"additionalProperties": false,
"description": "Catalogue records that fit when a level is ambiguous, at most ten per level; `fields./identity/body.candidate_count` or `fields./identity/drivetrain.candidate_count` has the total. Left out when nothing is ambiguous.",
"properties": {
"generation": {
"type": "array",
"maxItems": 10,
"items": {
"$ref": "#/components/schemas/VehicleCandidate"
},
"description": "Generations that fit, oldest first."
},
"drivetrain": {
"type": "array",
"maxItems": 10,
"items": {
"$ref": "#/components/schemas/VehicleCandidate"
},
"description": "Drivetrains of the identified generation that fit, closest to the supplied power first."
}
}
},
"fields": {
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/VehicleFieldProvenance"
},
"description": "Provenance per value, keyed by JSON Pointer into `vehicle`, such as `/specification/powertrain/powerHp`, `/identity/drivetrain` or `/vehicle/odometer`. A value without provenance here was not stated by anyone; an ambiguous level appears without a value."
}
}
}VehicleCatalogueRef
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"name"
],
"description": "One identity level of the vehicle: an AutoUncle catalogue record. `id` is never a provider's own ID.",
"properties": {
"id": {
"type": [
"string",
"null"
],
"minLength": 1,
"description": "Catalogue ID (a UUID), the same ID the catalogue API returns and a request accepts. Null only when `status` is `unidentified`: the name is then as you or the register gave it, and the catalogue does not know it."
},
"name": {
"type": "string",
"minLength": 1,
"description": "Catalogue name, for example `Golf VIII` or `1.5 TSI (130 Hp) DSG`. In an `unidentified` vehicle, the name as you or the register spelled it."
},
"from_year": {
"type": "integer",
"description": "Generation only: first production year."
},
"to_year": {
"type": "integer",
"description": "Generation only: last production year. Absent while the generation is in production."
}
}
}VehicleSpecs
{
"type": "object",
"additionalProperties": false,
"description": "Technical facts. With an identified drivetrain they are the catalogue's values; otherwise the values you sent, a register gave or that were read from your text. Absent when unknown.",
"properties": {
"body": {
"type": "string",
"enum": [
"hatchback",
"estate",
"suv",
"sedan",
"mpv",
"convertible",
"coupe"
],
"x-extensible-enum": true,
"description": "Body type."
},
"doors": {
"type": "integer",
"minimum": 1,
"maximum": 10,
"description": "Number of doors."
},
"seats": {
"type": "integer",
"minimum": 1,
"maximum": 20,
"description": "Number of seats."
},
"energy": {
"type": "object",
"additionalProperties": false,
"description": "Energy source.",
"properties": {
"fuel": {
"type": "string",
"enum": [
"petrol",
"diesel",
"electric",
"hybrid",
"plug_in_hybrid_petrol",
"plug_in_hybrid_diesel",
"lpg",
"cng",
"ethanol",
"hydrogen"
],
"description": "Fuel or electrification type, from the public vocabulary of /v1/catalogue/enums."
}
}
},
"power": {
"type": "object",
"additionalProperties": false,
"description": "Engine or drivetrain power. Returned in both units; on input `hp` wins over `kw`.",
"properties": {
"hp": {
"type": "number",
"minimum": 0,
"maximum": 3000,
"description": "Power in horsepower."
},
"kw": {
"type": "number",
"minimum": 0,
"maximum": 2300,
"description": "Power in kilowatts, rounded. On input it is converted to horsepower (1 kW = 1.35962 hp) when `hp` is absent."
}
}
},
"engine_size_l": {
"type": "number",
"minimum": 0,
"maximum": 30,
"description": "Combustion engine displacement in litres, such as 1.5."
},
"transmission": {
"type": "object",
"additionalProperties": false,
"description": "Gearbox. Absent when unknown; absent does not mean manual.",
"properties": {
"type": {
"type": "string",
"enum": [
"manual",
"automatic"
],
"description": "Gearbox type."
}
}
},
"traction": {
"type": "string",
"enum": [
"fwd",
"rwd",
"2wd",
"awd",
"4wd"
],
"description": "Driven wheels. `2wd` means two-wheel drive with the driven axle not recorded, which is what the catalogue knows for most cars."
},
"battery_kwh": {
"type": "number",
"minimum": 0,
"maximum": 500,
"description": "Traction battery capacity in kilowatt-hours."
},
"electric_range_km": {
"type": "number",
"minimum": 0,
"maximum": 3000,
"description": "Electric driving range in kilometres."
}
}
}VehicleFieldProvenance
{
"type": "object",
"additionalProperties": false,
"required": [
"basis",
"source",
"status"
],
"description": "Where one vehicle value came from and whether the catalogue confirmed it.",
"properties": {
"basis": {
"type": "string",
"enum": [
"observed",
"extracted",
"catalogue",
"assumed"
],
"x-extensible-enum": true,
"description": "How the value was established: observed (supplied by you or read from a register record), extracted (parsed or automatically interpreted from your text or photos), catalogue (derived from or matched against the AutoUncle catalogue) or assumed (a default, not evidence about this vehicle)."
},
"source": {
"type": "string",
"enum": [
"provided",
"registry",
"catalogue_id",
"catalogue_match",
"catalogue_derived",
"text_parser",
"ai_text",
"ai_vision",
"imputed",
"default"
],
"x-extensible-enum": true,
"description": "What supplied it: provided (you sent it), registry (a register or decoder, named in `source_id`), catalogue_id (a catalogue ID you sent), catalogue_match (matched from names and specs), catalogue_derived (read from a catalogue record you pinned), text_parser, ai_text or ai_vision (read from your text or photos), imputed or default."
},
"source_id": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$",
"description": "The `source_id` in `attributions` that supplied the value, when it came from a data source such as a register."
},
"evidence_source_id": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$",
"description": "The data source, also listed in attributions, that stated what the catalogue checked: for an identity level matched from a register's or decoder's names, the source of those names; for a confirmed or conflicting spec, the register that stated the value (otherwise you did)."
},
"status": {
"type": "string",
"enum": [
"supplied",
"extracted",
"confirmed",
"derived",
"conflict",
"ambiguous",
"assumed",
"unmatched"
],
"x-extensible-enum": true,
"description": "supplied: only you or a register give the value; nothing could check it. extracted: only your text or photos give the value, as the rules parser or AI interpretation read it; nothing could check it. confirmed: your value agrees with the identified drivetrain. derived: the catalogue gives it. conflict: your value contradicts the identified drivetrain; the catalogue's value is used and yours is in `supplied`. ambiguous: not determined, see `candidates`. assumed: a default, not evidence. unmatched: an identity level the catalogue could not match; its `id` is null."
},
"supplied": {
"description": "With status conflict: the value you sent, or the register named in `evidence_source_id` stated. It was not used."
},
"confidence": {
"type": [
"number",
"null"
],
"minimum": 0,
"maximum": 1,
"description": "Confidence from 0 to 1 for an interpreted value, or null."
},
"match_score": {
"type": "number",
"description": "Catalogue match score from 0 to 1 for an identity level that was matched rather than supplied."
},
"selected_by": {
"type": "string",
"enum": [
"ai_text",
"caller_evidence"
],
"x-extensible-enum": true,
"description": "How a catalogue record was chosen among records the catalogue could not separate: ai_text (automated interpretation of your description) or caller_evidence (the fuel, power, drive or transmission you sent)."
},
"candidate_count": {
"type": "integer",
"minimum": 0,
"description": "With status ambiguous: how many catalogue records fit. At most ten are listed in `candidates`."
}
}
}VehicleCandidate
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"name"
],
"description": "A catalogue record that fits what is known when a level is ambiguous. Send its `id` back to settle the level.",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"description": "Catalogue ID of the record."
},
"name": {
"type": "string",
"minLength": 1,
"description": "Catalogue name of the record."
},
"score": {
"type": [
"number",
"null"
],
"description": "The resolver's score for the tied records, or null when the candidates were not scored."
},
"from_year": {
"type": "integer",
"description": "Generation candidates: first production year."
},
"to_year": {
"type": "integer",
"description": "Generation candidates: last production year. Absent while in production."
},
"body": {
"type": "string",
"description": "Generation candidates: the catalogue's body type."
},
"specs": {
"$ref": "#/components/schemas/VehicleSpecs",
"description": "Drivetrain candidates: the drivetrain's technical facts."
},
"mismatches": {
"type": "array",
"items": {
"type": "string"
},
"description": "Drivetrain candidates: JSON Pointers of supplied values this candidate contradicts. Empty for the candidates listed today."
}
}
}Problem
{
"type": "object",
"required": [
"type",
"title",
"status",
"code",
"detail",
"request_id",
"billable",
"errors",
"fix",
"docs_url",
"retryable"
],
"properties": {
"type": {
"type": "string",
"maxLength": 200
},
"title": {
"type": "string",
"maxLength": 200
},
"status": {
"type": "integer"
},
"code": {
"type": "string",
"maxLength": 200
},
"detail": {
"type": "string",
"maxLength": 2000
},
"request_id": {
"type": [
"string",
"null"
]
},
"billable": {
"const": false
},
"errors": {
"type": "array",
"description": "Affected request fields, when known.",
"items": {
"type": "object",
"properties": {
"pointer": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"pointer",
"message"
],
"additionalProperties": false
}
},
"fix": {
"type": "array",
"description": "Actionable recovery steps, including replay guidance when relevant.",
"minItems": 1,
"items": {
"type": "string",
"minLength": 1
}
},
"docs_url": {
"type": "string",
"maxLength": 200
},
"retryable": {
"type": "boolean",
"description": "Whether retrying after the documented recovery steps may succeed. Follow fix for waiting, input changes and idempotency-key/replay semantics."
},
"service": {
"type": "string",
"description": "Safe public service identifier, never a private hostname or provider response."
},
"reason": {
"type": "string",
"description": "Safe enumerated domain refusal reason when known."
},
"retry_after": {
"type": "integer",
"minimum": 1,
"description": "Seconds to wait before retrying, when known. Equals the Retry-After header on REST and is the only retry delay over MCP, which has no response headers."
}
},
"additionalProperties": false
}Note
{
"type": "object",
"description": "A standing limitation, disclaimer or legal notice for this result. Request-specific input and uncertainty problems are reported in warnings, operational failures in error, and field provenance in source/basis.",
"properties": {
"code": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$",
"description": "Stable machine-readable note code. Match on code, not message."
},
"category": {
"type": "string",
"enum": [
"disclaimer",
"limitation",
"legal_notice"
],
"description": "disclaimer: how the result may be relied on; limitation: where the result does not apply or is weaker; legal_notice: verified wording a data source requires to be shown."
},
"message": {
"type": "string",
"minLength": 1
},
"pointers": {
"type": "array",
"items": {
"type": "string",
"pattern": "^(/[^/]+)*$",
"description": "JSON Pointer (RFC 6901) into this result."
},
"description": "Parts of the result the note applies to; empty when it applies to the whole result."
},
"source_ids": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$"
},
"description": "Attributed sources that caused the note; empty for general notes."
}
},
"additionalProperties": false,
"required": [
"code",
"category",
"message",
"pointers",
"source_ids"
]
}Attribution
{
"type": "object",
"description": "A data source that actually contributed to this result. Sources that were enabled but did not contribute are never listed.",
"properties": {
"source_id": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$",
"description": "Stable source identifier. Safe to store and compare."
},
"name": {
"type": "string",
"minLength": 1,
"description": "Public source name."
},
"url": {
"type": [
"string",
"null"
],
"description": "Public page describing the source, when one exists."
},
"party": {
"type": "string",
"enum": [
"first_party",
"third_party"
],
"description": "first_party: AutoUncle's own data or models; third_party: an external provider or dataset."
},
"role": {
"type": "string",
"enum": [
"vehicle_catalogue",
"valuation_model",
"ai_interpretation",
"vehicle_registry",
"market_listings",
"selling_time_model"
]
},
"license": {
"description": "Licence or terms governing this source's contribution, or null when not yet verified.",
"oneOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$"
},
"name": {
"type": "string",
"minLength": 1
},
"url": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false,
"required": [
"id",
"name",
"url"
]
}
]
},
"attribution_text": {
"type": [
"string",
"null"
],
"description": "Attribution wording you must display wherever you show or redistribute the contributing data. Null when none is required or when the wording is still pending review; never drop or shorten it when present."
},
"notice_status": {
"type": "string",
"enum": [
"verified",
"pending_review"
],
"description": "verified: licence and wording checked against an authoritative source. pending_review: obligations are not yet verified; do not infer that none apply."
},
"notice_version": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*@[0-9]+$",
"description": "Registry revision in force when the result was produced. Stored read-backs and idempotent replays keep this snapshot."
},
"pointers": {
"type": "array",
"items": {
"type": "string",
"pattern": "^(/[^/]+)*$",
"description": "JSON Pointer (RFC 6901) into this result."
},
"description": "Parts of the result this source contributed to."
}
},
"additionalProperties": false,
"required": [
"source_id",
"name",
"url",
"party",
"role",
"license",
"attribution_text",
"notice_status",
"notice_version",
"pointers"
]
}Notes
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Note"
},
"description": "Always present. An empty array means no standing limitation, disclaimer or legal notice applies beyond this contract. Never truncated."
}Attributions
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Attribution"
},
"description": "Always present. Lists only sources that contributed to this result. An empty array means the result contains no source data (refusals, failures and metadata responses). Never truncated to fit an output limit."
}CatalogueBrand
{
"type": "object",
"description": "A vehicle make.",
"properties": {
"id": {
"type": "string",
"description": "Brand ID, for example `b-0957579dc5bca6de229d2f32`. Opaque: store it as returned.",
"minLength": 1
},
"name": {
"type": "string",
"description": "Catalogue brand name, for example `VW`."
},
"object": {
"type": "string",
"const": "brand",
"description": "Always `brand`."
}
},
"required": [
"id",
"name",
"object"
],
"additionalProperties": false
}CatalogueModel
{
"type": "object",
"description": "A model of a make. Some models are aliases that stand for generations of other models.",
"properties": {
"id": {
"type": "string",
"description": "Model ID, for example `cm-6bb52590daf6d1b19108ec93`.",
"minLength": 1
},
"name": {
"type": "string",
"description": "Model name without the brand, for example `Golf`."
},
"object": {
"type": "string",
"const": "model",
"description": "Always `model`."
},
"brand_id": {
"type": "string",
"description": "Parent brand ID.",
"minLength": 1
}
},
"required": [
"id",
"name",
"object",
"brand_id"
],
"additionalProperties": false
}CatalogueGeneration
{
"type": "object",
"description": "A generation (and body variant) of a model.",
"properties": {
"id": {
"type": "string",
"description": "Generation ID, for example `mg-40c5d8de40bb48ae60fc0a6c`.",
"minLength": 1
},
"name": {
"type": "string",
"description": "Generation name, including body variant where relevant, for example `Golf VIII Variant`."
},
"object": {
"type": "string",
"const": "generation",
"description": "Always `generation`."
},
"model_id": {
"type": "string",
"description": "Parent model ID.",
"minLength": 1
},
"from_year": {
"type": "integer",
"description": "First production year. Omitted when unknown."
},
"to_year": {
"type": "integer",
"description": "Last production year. Omitted when unknown or still in production."
},
"body": {
"type": "string",
"description": "Catalogue body type. Omitted when unknown."
}
},
"required": [
"id",
"name",
"object",
"model_id"
],
"additionalProperties": false
}CatalogueDrivetrain
{
"type": "object",
"description": "An engine and transmission variant of a generation.",
"properties": {
"id": {
"type": "string",
"description": "Drivetrain ID, for example `dv-947a3199394a5a4b41cb2869`.",
"minLength": 1
},
"name": {
"type": "string",
"description": "Engine and transmission designation, for example `1.5 TSI (130 Hp)`."
},
"object": {
"type": "string",
"const": "drivetrain",
"description": "Always `drivetrain`."
},
"generation_id": {
"type": "string",
"description": "Parent generation ID.",
"minLength": 1
},
"fuel": {
"type": "string",
"description": "Fuel. Usually a public fuel value such as `petrol`, `diesel` or `plug_in_hybrid_petrol`; some catalogue values, such as `CNG_Hybrid`, are passed through unchanged. Omitted when unknown."
},
"power_hp": {
"type": "number",
"description": "Power in horsepower. Omitted when unknown."
},
"transmission": {
"type": "string",
"description": "Lowercase catalogue transmission, usually `manual` or `automatic`. Omitted when unknown."
},
"engine_size_l": {
"type": "number",
"description": "Engine displacement in litres. Omitted when unknown."
},
"battery_kwh": {
"type": "number",
"description": "Battery capacity in kWh for electrified drivetrains. Omitted when unknown."
},
"drive": {
"type": "string",
"description": "Catalogue traction label, for example `2WD` or `AWD`. Note that this is not the `fwd`/`rwd`/`awd`/`4wd` value used in `vehicle.drive`. Omitted when unknown."
},
"doors": {
"type": "integer",
"description": "Number of doors. Omitted when unknown."
}
},
"required": [
"id",
"name",
"object",
"generation_id"
],
"additionalProperties": false
}CatalogueEquipmentVariant
{
"type": "object",
"description": "A trim or equipment line of a make.",
"properties": {
"id": {
"type": "string",
"description": "Equipment variant ID, for example `ev-227a3875b490f1310578b286`.",
"minLength": 1
},
"name": {
"type": "string",
"description": "Trim or equipment line name, for example `Active`."
},
"object": {
"type": "string",
"const": "equipment_variant",
"description": "Always `equipment_variant`."
},
"brand_id": {
"type": "string",
"description": "Parent brand ID. Omitted when the catalogue has no brand for it.",
"minLength": 1
}
},
"required": [
"id",
"name",
"object"
],
"additionalProperties": false
}CatalogueSearchResult
{
"type": "object",
"description": "A make or model matching the search text.",
"properties": {
"id": {
"type": "string",
"description": "Brand or model ID.",
"minLength": 1
},
"name": {
"type": "string",
"description": "Brand name, or model name without the brand (for example `Golf Alltrack`)."
},
"object": {
"type": "string",
"enum": [
"brand",
"model"
],
"description": "`brand` or `model`."
},
"brand_id": {
"type": "string",
"description": "Parent brand ID. Models only.",
"minLength": 1
}
},
"required": [
"id",
"name",
"object"
],
"additionalProperties": false
}CatalogueBrandList
{
"type": "object",
"description": "Vehicle makes.",
"properties": {
"object": {
"type": "string",
"const": "list",
"description": "Always `list`."
},
"version": {
"type": "string",
"description": "Catalogue version, for example `5.6.7:NEW`. Refresh cached catalogue data when it changes.",
"minLength": 1
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CatalogueBrand"
},
"description": "The items, sorted by name. Not paginated."
},
"notes": {
"$ref": "#/components/schemas/Notes",
"description": "Notes for this result. Usually empty."
},
"attributions": {
"$ref": "#/components/schemas/Attributions",
"description": "The catalogue attribution, pointing at `/data`, when the list contains catalogue data."
}
},
"required": [
"object",
"version",
"data",
"notes",
"attributions"
],
"additionalProperties": false
}CatalogueModelList
{
"type": "object",
"description": "Models of one make.",
"properties": {
"object": {
"type": "string",
"const": "list",
"description": "Always `list`."
},
"version": {
"type": "string",
"description": "Catalogue version, for example `5.6.7:NEW`. Refresh cached catalogue data when it changes.",
"minLength": 1
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CatalogueModel"
},
"description": "The items, sorted by name. Not paginated."
},
"notes": {
"$ref": "#/components/schemas/Notes",
"description": "Notes for this result. Usually empty."
},
"attributions": {
"$ref": "#/components/schemas/Attributions",
"description": "The catalogue attribution, pointing at `/data`, when the list contains catalogue data."
}
},
"required": [
"object",
"version",
"data",
"notes",
"attributions"
],
"additionalProperties": false
}CatalogueGenerationList
{
"type": "object",
"description": "Generations of one model, optionally narrowed by year.",
"properties": {
"object": {
"type": "string",
"const": "list",
"description": "Always `list`."
},
"version": {
"type": "string",
"description": "Catalogue version, for example `5.6.7:NEW`. Refresh cached catalogue data when it changes.",
"minLength": 1
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CatalogueGeneration"
},
"description": "The items, sorted by name. Not paginated."
},
"notes": {
"$ref": "#/components/schemas/Notes",
"description": "Notes for this result. Usually empty."
},
"attributions": {
"$ref": "#/components/schemas/Attributions",
"description": "The catalogue attribution, pointing at `/data`, when the list contains catalogue data."
}
},
"required": [
"object",
"version",
"data",
"notes",
"attributions"
],
"additionalProperties": false
}CatalogueDrivetrainList
{
"type": "object",
"description": "Drivetrains of one generation, optionally filtered.",
"properties": {
"object": {
"type": "string",
"const": "list",
"description": "Always `list`."
},
"version": {
"type": "string",
"description": "Catalogue version, for example `5.6.7:NEW`. Refresh cached catalogue data when it changes.",
"minLength": 1
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CatalogueDrivetrain"
},
"description": "The items, sorted by name. Not paginated."
},
"notes": {
"$ref": "#/components/schemas/Notes",
"description": "Notes for this result. Usually empty."
},
"attributions": {
"$ref": "#/components/schemas/Attributions",
"description": "The catalogue attribution, pointing at `/data`, when the list contains catalogue data."
}
},
"required": [
"object",
"version",
"data",
"notes",
"attributions"
],
"additionalProperties": false
}CatalogueEquipmentVariantList
{
"type": "object",
"description": "Equipment variants of one make.",
"properties": {
"object": {
"type": "string",
"const": "list",
"description": "Always `list`."
},
"version": {
"type": "string",
"description": "Catalogue version, for example `5.6.7:NEW`. Refresh cached catalogue data when it changes.",
"minLength": 1
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CatalogueEquipmentVariant"
},
"description": "The items, sorted by name. Not paginated."
},
"notes": {
"$ref": "#/components/schemas/Notes",
"description": "Notes for this result. Usually empty."
},
"attributions": {
"$ref": "#/components/schemas/Attributions",
"description": "The catalogue attribution, pointing at `/data`, when the list contains catalogue data."
}
},
"required": [
"object",
"version",
"data",
"notes",
"attributions"
],
"additionalProperties": false
}CatalogueSearchResults
{
"type": "object",
"description": "Makes and models matching the search text: up to 20 brands, then up to 80 models.",
"properties": {
"object": {
"type": "string",
"const": "list",
"description": "Always `list`."
},
"version": {
"type": "string",
"description": "Catalogue version, for example `5.6.7:NEW`. Refresh cached catalogue data when it changes.",
"minLength": 1
},
"data": {
"type": "array",
"maxItems": 100,
"items": {
"$ref": "#/components/schemas/CatalogueSearchResult"
},
"description": "Matching brands first, then matching models. Not paginated."
},
"notes": {
"$ref": "#/components/schemas/Notes",
"description": "Notes for this result. Usually empty."
},
"attributions": {
"$ref": "#/components/schemas/Attributions",
"description": "The catalogue attribution, pointing at `/data`, when the list contains catalogue data."
}
},
"required": [
"object",
"version",
"data",
"notes",
"attributions"
],
"additionalProperties": false
}CatalogueItem
{
"description": "One catalogue item with the same fields as in its list endpoint, plus notes and attributions. `object` tells which kind it is.",
"oneOf": [
{
"$ref": "#/components/schemas/CatalogueBrandItem"
},
{
"$ref": "#/components/schemas/CatalogueModelItem"
},
{
"$ref": "#/components/schemas/CatalogueGenerationItem"
},
{
"$ref": "#/components/schemas/CatalogueDrivetrainItem"
},
{
"$ref": "#/components/schemas/CatalogueEquipmentVariantItem"
}
]
}CatalogueBrandItem
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Brand ID, for example `b-0957579dc5bca6de229d2f32`. Opaque: store it as returned.",
"minLength": 1
},
"name": {
"type": "string",
"description": "Catalogue brand name, for example `VW`."
},
"object": {
"type": "string",
"const": "brand",
"description": "Always `brand`."
},
"notes": {
"$ref": "#/components/schemas/Notes",
"description": "Notes for this result."
},
"attributions": {
"$ref": "#/components/schemas/Attributions",
"description": "The catalogue attribution."
}
},
"required": [
"id",
"name",
"object",
"notes",
"attributions"
],
"additionalProperties": false,
"description": "One brand with notes and attributions."
}CatalogueModelItem
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Model ID, for example `cm-6bb52590daf6d1b19108ec93`.",
"minLength": 1
},
"name": {
"type": "string",
"description": "Model name without the brand, for example `Golf`."
},
"object": {
"type": "string",
"const": "model",
"description": "Always `model`."
},
"brand_id": {
"type": "string",
"description": "Parent brand ID.",
"minLength": 1
},
"notes": {
"$ref": "#/components/schemas/Notes",
"description": "Notes for this result."
},
"attributions": {
"$ref": "#/components/schemas/Attributions",
"description": "The catalogue attribution."
}
},
"required": [
"id",
"name",
"object",
"brand_id",
"notes",
"attributions"
],
"additionalProperties": false,
"description": "One model with notes and attributions."
}CatalogueGenerationItem
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Generation ID, for example `mg-40c5d8de40bb48ae60fc0a6c`.",
"minLength": 1
},
"name": {
"type": "string",
"description": "Generation name, including body variant where relevant, for example `Golf VIII Variant`."
},
"object": {
"type": "string",
"const": "generation",
"description": "Always `generation`."
},
"model_id": {
"type": "string",
"description": "Parent model ID.",
"minLength": 1
},
"from_year": {
"type": "integer",
"description": "First production year. Omitted when unknown."
},
"to_year": {
"type": "integer",
"description": "Last production year. Omitted when unknown or still in production."
},
"body": {
"type": "string",
"description": "Catalogue body type. Omitted when unknown."
},
"notes": {
"$ref": "#/components/schemas/Notes",
"description": "Notes for this result."
},
"attributions": {
"$ref": "#/components/schemas/Attributions",
"description": "The catalogue attribution."
}
},
"required": [
"id",
"name",
"object",
"model_id",
"notes",
"attributions"
],
"additionalProperties": false,
"description": "One generation with notes and attributions."
}CatalogueDrivetrainItem
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Drivetrain ID, for example `dv-947a3199394a5a4b41cb2869`.",
"minLength": 1
},
"name": {
"type": "string",
"description": "Engine and transmission designation, for example `1.5 TSI (130 Hp)`."
},
"object": {
"type": "string",
"const": "drivetrain",
"description": "Always `drivetrain`."
},
"generation_id": {
"type": "string",
"description": "Parent generation ID.",
"minLength": 1
},
"fuel": {
"type": "string",
"description": "Fuel. Usually a public fuel value such as `petrol`, `diesel` or `plug_in_hybrid_petrol`; some catalogue values, such as `CNG_Hybrid`, are passed through unchanged. Omitted when unknown."
},
"power_hp": {
"type": "number",
"description": "Power in horsepower. Omitted when unknown."
},
"transmission": {
"type": "string",
"description": "Lowercase catalogue transmission, usually `manual` or `automatic`. Omitted when unknown."
},
"engine_size_l": {
"type": "number",
"description": "Engine displacement in litres. Omitted when unknown."
},
"battery_kwh": {
"type": "number",
"description": "Battery capacity in kWh for electrified drivetrains. Omitted when unknown."
},
"drive": {
"type": "string",
"description": "Catalogue traction label, for example `2WD` or `AWD`. Note that this is not the `fwd`/`rwd`/`awd`/`4wd` value used in `vehicle.drive`. Omitted when unknown."
},
"doors": {
"type": "integer",
"description": "Number of doors. Omitted when unknown."
},
"notes": {
"$ref": "#/components/schemas/Notes",
"description": "Notes for this result."
},
"attributions": {
"$ref": "#/components/schemas/Attributions",
"description": "The catalogue attribution."
}
},
"required": [
"id",
"name",
"object",
"generation_id",
"notes",
"attributions"
],
"additionalProperties": false,
"description": "One drivetrain with notes and attributions."
}CatalogueEquipmentVariantItem
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Equipment variant ID, for example `ev-227a3875b490f1310578b286`.",
"minLength": 1
},
"name": {
"type": "string",
"description": "Trim or equipment line name, for example `Active`."
},
"object": {
"type": "string",
"const": "equipment_variant",
"description": "Always `equipment_variant`."
},
"brand_id": {
"type": "string",
"description": "Parent brand ID. Omitted when the catalogue has no brand for it.",
"minLength": 1
},
"notes": {
"$ref": "#/components/schemas/Notes",
"description": "Notes for this result."
},
"attributions": {
"$ref": "#/components/schemas/Attributions",
"description": "The catalogue attribution."
}
},
"required": [
"id",
"name",
"object",
"notes",
"attributions"
],
"additionalProperties": false,
"description": "One equipment variant with notes and attributions."
}CatalogueEnums
{
"type": "object",
"description": "The values accepted by enumerated request fields.",
"properties": {
"object": {
"type": "string",
"const": "enums",
"description": "Always `enums`."
},
"data": {
"type": "object",
"description": "Accepted values per request field.",
"properties": {
"fuel": {
"type": "array",
"items": {
"type": "string"
},
"description": "Public fuel values accepted in `vehicle.fuel`."
},
"transmission": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values accepted in `vehicle.transmission`: `manual`, `automatic`."
},
"drive": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values accepted in `vehicle.drive`: `fwd`, `rwd`, `awd`, `4wd`."
},
"mileage_units": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values accepted in `vehicle.mileage.unit`: `km`, `mi`, `mil`."
},
"price_basis": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values accepted in `pricing.price_basis`: `dealer_retail`, `private_sale`."
},
"resolution": {
"type": "array",
"items": {
"type": "string"
},
"description": "Values accepted in `options.resolution`: `auto`, `no_ai`, `strict`."
},
"precision": {
"type": "array",
"items": {
"type": "string"
},
"description": "Precision grades, best first, accepted in `options.min_precision`: `high`, `medium`, `low`, `indicative`."
},
"equipment": {
"type": "array",
"items": {
"type": "string"
},
"description": "Equipment feature keys accepted in `vehicle.equipment` and returned in a Vehicle's `equipment`, such as `EXTERIOR_TOWBAR_FIXED` or `BATTERY_HEAT_PUMP`."
}
},
"required": [
"fuel",
"transmission",
"drive",
"mileage_units",
"price_basis",
"resolution",
"precision",
"equipment"
],
"additionalProperties": false
},
"notes": {
"$ref": "#/components/schemas/Notes",
"description": "Always empty."
},
"attributions": {
"$ref": "#/components/schemas/Attributions",
"description": "Always empty."
}
},
"required": [
"object",
"data",
"notes",
"attributions"
],
"additionalProperties": false
}CatalogueCountries
{
"type": "object",
"description": "Every market the service can value, and whether new workspaces can value it.",
"properties": {
"object": {
"type": "string",
"const": "list",
"description": "Always `list`."
},
"data": {
"type": "array",
"description": "One entry per market.",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Market code to send as `country`, an ISO 3166-1 alpha-2 code such as `DK` or `GB`.",
"pattern": "^[A-Z]{2}$"
},
"mileage_unit": {
"type": "string",
"enum": [
"km",
"mi",
"mil"
],
"description": "The market's mileage unit."
},
"availability": {
"type": "string",
"enum": [
"general",
"on_request"
],
"description": "`general`: enabled for every new workspace. `on_request`: listed for completeness, but a workspace can value it only after AutoUncle enables it; until then a valuation returns 403 country_not_enabled. GET /v1/account shows what your workspace may value."
}
},
"required": [
"id",
"mileage_unit",
"availability"
],
"additionalProperties": false
}
},
"notes": {
"$ref": "#/components/schemas/Notes",
"description": "Always empty."
},
"attributions": {
"$ref": "#/components/schemas/Attributions",
"description": "Always empty."
}
},
"required": [
"object",
"data",
"notes",
"attributions"
],
"additionalProperties": false
}CatalogueVersion
{
"type": "object",
"description": "The current catalogue version.",
"properties": {
"version": {
"type": "string",
"description": "Catalogue version, for example `5.6.7:NEW`. Refresh cached catalogue data when it changes.",
"minLength": 1
},
"notes": {
"$ref": "#/components/schemas/Notes",
"description": "Always empty."
},
"attributions": {
"$ref": "#/components/schemas/Attributions",
"description": "Always empty."
}
},
"required": [
"version",
"notes",
"attributions"
],
"additionalProperties": false
}Account
{
"type": "object",
"description": "The workspace and API key that made the call.",
"properties": {
"object": {
"type": "string",
"const": "account",
"description": "Always `account`."
},
"organization": {
"type": "object",
"description": "The workspace that owns the key.",
"properties": {
"id": {
"type": "string",
"description": "Workspace ID (`org_…`).",
"pattern": "^org_[A-Za-z0-9]+$"
},
"name": {
"type": "string",
"description": "Workspace name."
}
},
"required": [
"id",
"name"
],
"additionalProperties": false
},
"key": {
"type": "object",
"description": "The API key that made this call.",
"properties": {
"id": {
"type": "string",
"description": "Key ID (`key_…`). Safe to log; it is not the secret.",
"pattern": "^key_[A-Za-z0-9]+$"
},
"mode": {
"type": "string",
"enum": [
"test",
"live"
],
"description": "`test` (simulated, free) or `live`."
},
"scopes": {
"type": "array",
"items": {
"type": "string",
"enum": [
"valuations:write",
"valuations:read",
"catalogue:read",
"account:read",
"vehicles:read"
]
},
"description": "Scopes granted to the key."
}
},
"required": [
"id",
"mode",
"scopes"
],
"additionalProperties": false
},
"credits_remaining": {
"type": "integer",
"minimum": 0,
"description": "Valuation credits available to the workspace now."
},
"allowed_countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Markets this key can value, as the ISO codes requests use in `country` (for example `DK`, `GB`, `DE`): the workspace's markets narrowed by the key's own allowed countries. When neither restricts the markets, every market is listed; the list is empty only when the key's markets and the workspace's do not overlap."
},
"rate_limit_per_minute": {
"type": "integer",
"minimum": 1,
"description": "Requests allowed per minute for the workspace in the valuations bucket, and separately in the vehicles bucket (default 60 each). Catalogue requests have their own limit."
},
"notes": {
"$ref": "#/components/schemas/Notes",
"description": "Always empty for account results."
},
"attributions": {
"$ref": "#/components/schemas/Attributions",
"description": "Always empty for account results."
}
},
"required": [
"object",
"organization",
"key",
"credits_remaining",
"allowed_countries",
"rate_limit_per_minute",
"notes",
"attributions"
],
"additionalProperties": false
}VinDecodeRequest
{
"type": "object",
"description": "A VIN to decode.",
"additionalProperties": false,
"required": [
"vin",
"country"
],
"properties": {
"vin": {
"type": "string",
"minLength": 17,
"maxLength": 40,
"description": "The 17-character VIN. Spaces and lower case are accepted; look-alike characters (O for 0, I for 1) are never repaired, and a VIN containing I, O or Q is rejected."
},
"country": {
"type": "string",
"pattern": "^[A-Za-z]{2}$",
"description": "Your market for this lookup, as an ISO 3166-1 alpha-2 code from GET /v1/catalogue/countries. It scopes key permissions and logging; it is never treated as the car's original market."
},
"market": {
"type": "string",
"pattern": "^[A-Za-z]{2}$",
"description": "The car's original sales market (ISO 3166-1 alpha-2), only when you know it independently. Never derive it from your market or the registration country."
},
"model_year": {
"type": "integer",
"minimum": 1886,
"maximum": 2100,
"description": "The model year, only when you know it independently. A first registration or production year does not establish it."
}
}
}HsnTsnRequest
{
"type": "object",
"description": "German type codes to look up.",
"additionalProperties": false,
"required": [
"hsn",
"tsn"
],
"properties": {
"hsn": {
"type": "string",
"minLength": 4,
"maxLength": 8,
"description": "Herstellerschlüsselnummer, field 2.1: four digits, sent as a string so leading zeroes are kept."
},
"tsn": {
"type": "string",
"minLength": 3,
"maxLength": 8,
"description": "The first three characters of the Typschlüsselnummer, field 2.2. Longer codes are rejected rather than truncated."
},
"country": {
"type": "string",
"pattern": "^[A-Za-z]{2}$",
"description": "Your market for this lookup (ISO 3166-1 alpha-2). Defaults to DE. The codes are always KBA codes."
}
}
}PlateLookupRequest
{
"type": "object",
"additionalProperties": false,
"required": [
"country",
"plate"
],
"description": "A registration-plate lookup.",
"properties": {
"country": {
"type": "string",
"description": "Country of the plate, ISO 3166-1 alpha-2. Only DK is supported in this version.",
"minLength": 2,
"maxLength": 2,
"examples": [
"DK"
]
},
"plate": {
"type": "string",
"description": "Registration plate as printed. Spaces, dashes and dots are ignored and letters are matched case-insensitively. Danish plates have 2 to 7 letters and digits, including personal plates.",
"minLength": 1,
"maxLength": 20,
"examples": [
"AB12345"
]
}
}
}LookupFreshness
{
"type": [
"object",
"null"
],
"additionalProperties": false,
"description": "How current the answer is. Null for answers that came from no source.",
"properties": {
"retrieved_at": {
"type": "string",
"format": "date-time",
"description": "When the source answered (UTC). A cached answer keeps its original time."
},
"cached": {
"type": "boolean",
"description": "`true` when the answer came from AutoUncle's lookup cache."
},
"data_as_of": {
"type": [
"string",
"null"
],
"description": "The source's own reference date, when it reports one."
},
"dataset_version": {
"type": [
"string",
"null"
],
"description": "Decoder and dataset release that produced the answer."
}
}
}VehicleLookupResult
{
"type": "object",
"additionalProperties": false,
"required": [
"object",
"request_id",
"lookup",
"status",
"country",
"mode",
"synthetic",
"identification",
"freshness",
"improve_precision",
"warnings",
"notes",
"attributions",
"usage"
],
"description": "The vehicle a lookup found, identified against the catalogue, with provenance, improvement hints, warnings, notes, attributions and billing.",
"properties": {
"object": {
"type": "string",
"const": "vehicle_lookup",
"description": "Always `vehicle_lookup`."
},
"request_id": {
"type": "string",
"pattern": "^lkp_[A-Za-z0-9]+$",
"description": "Lookup ID (`lkp_…`), also in the `X-Lookup-Id` header. Shown in the console request log."
},
"lookup": {
"type": "string",
"enum": [
"vin",
"hsn_tsn",
"plate"
],
"x-extensible-enum": true,
"description": "Which lookup ran."
},
"status": {
"type": "string",
"enum": [
"resolved",
"suggested",
"ambiguous",
"no_match",
"unsupported",
"invalid_input"
],
"x-extensible-enum": true,
"description": "The source's answer, separate from how well the catalogue identified the vehicle (`vehicle.status`). resolved: the source established vehicle data; suggested: only conditional answers (read the notes); ambiguous: the source holds competing answers; no_match: a valid input the source does not know (not billed); unsupported and invalid_input: the source could not answer this input (not billed). Test keys always get resolved."
},
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Your market for this lookup, normalized (ISO 3166-1 alpha-2)."
},
"mode": {
"type": "string",
"enum": [
"live",
"test"
],
"description": "`test` for a test key, `live` for a live key."
},
"synthetic": {
"type": "boolean",
"description": "`true` for the fixed example a test key gets. A synthetic vehicle says nothing about your input."
},
"vehicle": {
"$ref": "#/components/schemas/Vehicle",
"description": "What the source says, identified against the AutoUncle catalogue, as an AVS vehicle document: catalogue identity where the catalogue knows the make, and the source's values otherwise. Provenance and candidates are in `identification`. A make the catalogue does not know gives `identification.status: unidentified`, with the stated brand and model names and no IDs. It is left out when the vehicle could not be identified to a brand and a model, with the reason in `identification`."
},
"identification": {
"$ref": "#/components/schemas/VehicleIdentification",
"description": "How the vehicle was identified: status, depth, candidates and the provenance of every value in `vehicle`."
},
"freshness": {
"$ref": "#/components/schemas/LookupFreshness"
},
"improve_precision": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string",
"minLength": 1
},
"reason": {
"type": "string",
"minLength": 1
},
"expected_impact": {
"type": "string",
"enum": [
"high",
"medium",
"low"
]
},
"message": {
"type": "string",
"minLength": 1
},
"candidates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"name": {
"type": "string",
"minLength": 1
},
"source": {
"type": "string",
"enum": [
"provided",
"catalogue_id",
"catalogue_derived",
"text_parser",
"registry",
"catalogue_match",
"ai_text",
"ai_vision",
"imputed",
"default"
]
},
"basis": {
"type": "string",
"enum": [
"observed",
"extracted",
"catalogue",
"assumed"
],
"description": "How the value was established: observed (supplied by the caller or read from a registry record), extracted (parsed or automatically interpreted from supplied text or photos), catalogue (deterministically derived from or matched against the AutoUncle catalogue) or assumed (a heuristic default or fixed baseline, not evidence about this vehicle)."
},
"match_score": {
"type": "number"
},
"ambiguous": {
"type": "boolean"
},
"candidate_count": {
"type": "integer",
"minimum": 2
}
},
"additionalProperties": false,
"required": [
"id",
"name",
"source"
]
}
}
},
"additionalProperties": false,
"required": [
"field",
"reason",
"expected_impact",
"message"
]
}
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$"
},
"message": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false,
"required": [
"code",
"message"
]
}
},
"notes": {
"$ref": "#/components/schemas/Notes"
},
"attributions": {
"$ref": "#/components/schemas/Attributions"
},
"usage": {
"type": "object",
"properties": {
"billable": {
"type": "boolean",
"description": "`true` when this lookup captured a credit."
},
"credits_used": {
"type": "integer",
"minimum": 0,
"maximum": 1,
"description": "Credits this call consumed (0 or 1)."
},
"original_credits_used": {
"type": "integer",
"minimum": 0,
"maximum": 1,
"description": "The same as `credits_used`: lookups are never replayed."
},
"charges": {
"type": "object",
"properties": {
"base": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": false
},
"credits_remaining": {
"type": "integer",
"minimum": 0,
"description": "Workspace credits left after this call."
},
"cache_hit": {
"type": "boolean",
"description": "`true` when the answer came from AutoUncle's lookup cache. Cached answers are billed like fresh ones."
},
"idempotent_replay": {
"type": "boolean",
"description": "Always false: lookups are not replayed."
},
"mode": {
"type": "string",
"enum": [
"live",
"test"
],
"description": "`test` or `live`."
}
},
"additionalProperties": false,
"required": [
"billable",
"credits_used",
"original_credits_used",
"charges",
"credits_remaining",
"cache_hit",
"idempotent_replay",
"mode"
],
"description": "Billing for this call."
}
}
}SellingTimeBand
{
"type": "object",
"additionalProperties": false,
"required": [
"rating",
"label",
"example_price",
"median_days",
"chance_sold_within"
],
"description": "The forecast for an asking price in the middle of one price-rating band.",
"properties": {
"rating": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"description": "AutoUncle price rating of the band, as in price_ratings.bands: 5 is super price, 1 is expensive."
},
"label": {
"type": "string",
"minLength": 1,
"description": "Plain-language name of the band."
},
"example_price": {
"type": "integer",
"minimum": 0,
"description": "The asking price the band's forecast is for, in the middle of the band, in currency, rounded to three significant figures."
},
"median_days": {
"type": [
"integer",
"null"
],
"minimum": 0,
"description": "Days after listing by which half of comparable vehicles are expected to have sold, in whole days. null when fewer than half are expected to sell within 26 weeks, the period a forecast covers."
},
"chance_sold_within": {
"type": "object",
"additionalProperties": false,
"required": [
"days_30",
"days_60",
"days_90"
],
"description": "Chance, from 0 to 1 in steps of 0.05, that the vehicle has sold within 30, 60 and 90 days of listing.",
"properties": {
"days_30": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Chance of selling within 30 days."
},
"days_60": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Chance of selling within 60 days."
},
"days_90": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Chance of selling within 90 days."
}
}
}
}
}SellingTimeAtAskingPrice
{
"type": "object",
"additionalProperties": false,
"required": [
"asking_price",
"rating",
"label",
"median_days",
"chance_sold_within"
],
"description": "The forecast at the asking price sent in pricing.asking_price.",
"properties": {
"asking_price": {
"type": "number",
"minimum": 0,
"description": "The asking price from pricing.asking_price, in currency."
},
"rating": {
"type": "integer",
"minimum": 0,
"maximum": 5,
"description": "AutoUncle price rating of the asking price, the same as price_ratings.asking_price_rating. 0 when it is outside the rating range."
},
"label": {
"type": "string",
"minLength": 1,
"description": "Plain-language name of the rating."
},
"median_days": {
"type": [
"integer",
"null"
],
"minimum": 0,
"description": "Days after listing by which half of comparable vehicles are expected to have sold, in whole days. null when fewer than half are expected to sell within 26 weeks, the period a forecast covers."
},
"chance_sold_within": {
"type": "object",
"additionalProperties": false,
"required": [
"days_30",
"days_60",
"days_90"
],
"description": "Chance, from 0 to 1 in steps of 0.05, that the vehicle has sold within 30, 60 and 90 days of listing.",
"properties": {
"days_30": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Chance of selling within 30 days."
},
"days_60": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Chance of selling within 60 days."
},
"days_90": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Chance of selling within 90 days."
}
}
}
}
}SellingTime
{
"type": "object",
"additionalProperties": false,
"required": [
"synthetic",
"currency",
"by_price_rating",
"at_asking_price"
],
"description": "Selling-time forecast, returned by POST /v1/selling-times only: how long the vehicle is expected to take to sell if it is listed now and its asking price is kept. A statistical forecast, not a guarantee; see the selling_time_is_forecast note.",
"properties": {
"synthetic": {
"type": "boolean",
"description": "true for a test-key forecast: fixed example figures, not market data."
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "ISO 4217 currency of example_price and asking_price, the valuation's currency."
},
"by_price_rating": {
"type": "array",
"minItems": 5,
"maxItems": 5,
"items": {
"$ref": "#/components/schemas/SellingTimeBand"
},
"description": "One forecast per price-rating band, from 5 (super price) to 1 (expensive): how pricing the vehicle sharper or higher changes how fast it sells."
},
"at_asking_price": {
"oneOf": [
{
"$ref": "#/components/schemas/SellingTimeAtAskingPrice"
},
{
"type": "null"
}
],
"description": "The forecast at pricing.asking_price, or null when the request has no asking price."
}
}
}SellingTimeResponse
{
"type": "object",
"description": "A valuation with its selling-time forecast. The same envelope as ValuationResponse (object is valuation, and the result can be read back with GET /v1/valuations/{id}); a valued result always carries selling_time.",
"allOf": [
{
"$ref": "#/components/schemas/ValuationResponse"
},
{
"if": {
"properties": {
"status": {
"const": "valued"
}
},
"required": [
"status"
]
},
"then": {
"required": [
"selling_time"
]
}
}
]
}MarketRequest
{
"type": "object",
"properties": {
"country": {
"type": "string",
"maxLength": 10,
"minLength": 2,
"description": "Market as an ISO 3166-1 alpha-2 code, such as DK, DE or GB. Every figure comes from that market's own listings only."
},
"vehicle": {
"$ref": "#/components/schemas/VehicleInput",
"description": "The vehicle, as a VehicleInput: an AVS vehicle document (any `vehicle` an endpoint returned, posted back unchanged) or the vehicle's attributes as a listing gives them."
},
"description": {
"type": "string",
"maxLength": 20000,
"minLength": 1,
"description": "Unstructured listing text describing the vehicle. Existing parsers and deployment-configured optional AI can propose attributes; the response identifies assumptions and unresolved inputs."
},
"images": {
"type": "array",
"minItems": 1,
"maxItems": 8,
"items": {
"type": "object",
"properties": {
"url": {
"type": "string",
"maxLength": 2048,
"format": "uri",
"description": "Public HTTPS image URL on port 443, without credentials or fragments. Private network destinations and redirects are rejected. Remote images must be supported image types and at most 8 MB each."
},
"data": {
"type": "string",
"maxLength": 1000000,
"description": "Strict base64-encoded image bytes, without a data-URL prefix. Inline data must also fit the total 1 MB API request limit."
},
"media_type": {
"type": "string",
"maxLength": 100,
"description": "MIME type for inline image bytes: image/jpeg, image/png, image/webp or image/gif. The actual image signature is checked."
}
},
"additionalProperties": false,
"anyOf": [
{
"required": [
"url"
]
},
{
"required": [
"data",
"media_type"
]
}
]
},
"description": "Up to eight vehicle photos, each supplied by HTTPS URL or inline base64 data, to identify the car type. AI image resolution is deployment-configured and never runs for test keys. Photos cost nothing extra on a market request."
},
"options": {
"type": "object",
"properties": {
"resolution": {
"type": "string",
"maxLength": 200,
"enum": [
"auto",
"no_ai",
"strict"
],
"description": "auto uses deterministic resolution and optional configured AI; no_ai and strict use deterministic resolution only."
}
},
"additionalProperties": false,
"description": "How the vehicle is resolved."
}
},
"additionalProperties": false,
"required": [
"country"
],
"anyOf": [
{
"required": [
"vehicle"
],
"properties": {
"vehicle": {
"minProperties": 1
}
}
},
{
"required": [
"description"
]
},
{
"required": [
"images"
]
}
],
"description": "A car type in one market: the same vehicle input as a valuation (a VehicleInput, a description or photos), of which at least a make and model must be recognised. Mileage and model year are optional and only narrow the segment as the similar-cars link does. Pricing does not apply."
}MarketResponse
{
"type": "object",
"additionalProperties": false,
"required": [
"request_id",
"object",
"status",
"country",
"mode",
"synthetic",
"identification",
"segment",
"as_of",
"supply",
"flow",
"turnover",
"demand",
"trend",
"suppressed",
"warnings",
"usage",
"notes",
"attributions"
],
"description": "Market & demand figures for a car type in one market: aggregates over the listings AutoUncle tracks there, never a listing.",
"properties": {
"request_id": {
"type": "string",
"pattern": "^mkt_[A-Za-z0-9]+$",
"description": "The request's ID, shown in the console request log."
},
"object": {
"type": "string",
"enum": [
"market"
]
},
"status": {
"type": "string",
"enum": [
"measured",
"partial",
"insufficient_data"
],
"description": "measured: figures were published; one credit on a live key. partial: a data store could not answer, so some figures are missing (see warnings); not charged. insufficient_data: every figure was withheld because too few listings match; not charged."
},
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$"
},
"mode": {
"type": "string",
"enum": [
"live",
"test"
]
},
"synthetic": {
"type": "boolean",
"description": "True for test keys: deterministic example figures, no market data."
},
"vehicle": {
"$ref": "#/components/schemas/Vehicle",
"description": "The identified vehicle. An AVS vehicle document; left out when the vehicle could not be identified to a brand and a model, with the reason in `identification`."
},
"identification": {
"$ref": "#/components/schemas/VehicleIdentification",
"description": "How the vehicle was identified: status, depth, candidates and the provenance of every value in `vehicle`."
},
"segment": {
"type": "object",
"additionalProperties": false,
"required": [
"criteria",
"similar_cars_url"
],
"properties": {
"criteria": {
"type": "object",
"additionalProperties": false,
"required": [
"make",
"model",
"model_year",
"mileage",
"fuel",
"transmission",
"body",
"engine_size_l"
],
"description": "What a listing must match to be in the segment, in the public vocabulary. Null means not restricted.",
"properties": {
"make": {
"type": "string"
},
"model": {
"type": "string"
},
"model_year": {
"type": [
"object",
"null"
],
"additionalProperties": false,
"required": [
"from",
"to"
],
"properties": {
"from": {
"type": [
"integer",
"null"
]
},
"to": {
"type": [
"integer",
"null"
]
}
}
},
"mileage": {
"type": [
"object",
"null"
],
"additionalProperties": false,
"required": [
"from",
"to",
"unit"
],
"properties": {
"from": {
"type": [
"integer",
"null"
]
},
"to": {
"type": [
"integer",
"null"
]
},
"unit": {
"type": "string",
"enum": [
"km",
"mi",
"mil"
]
}
}
},
"fuel": {
"type": [
"string",
"null"
]
},
"transmission": {
"type": [
"string",
"null"
],
"enum": [
"automatic",
"manual",
null
]
},
"body": {
"type": [
"string",
"null"
]
},
"engine_size_l": {
"type": [
"number",
"null"
]
}
}
},
"similar_cars_url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "The same segment as a search on the market's own AutoUncle site."
}
}
},
"as_of": {
"type": "string",
"format": "date-time",
"description": "When the figures were read. On-sale and left-the-market figures can be up to three hours old (shared cache)."
},
"supply": {
"type": [
"object",
"null"
],
"additionalProperties": false,
"required": [
"on_sale",
"on_sale_band"
],
"description": "Listings on sale now. Null when those figures could not be read (market_supply_unavailable warning).",
"properties": {
"on_sale": {
"type": [
"integer",
"null"
],
"description": "Listings on sale now in the segment. Null when fewer than 10, with on_sale_band set.",
"minimum": 0
},
"on_sale_band": {
"type": [
"string",
"null"
],
"enum": [
"fewer_than_10",
null
],
"description": "fewer_than_10 when the count is withheld; every other supply figure is then left out."
},
"price": {
"type": "object",
"additionalProperties": false,
"required": [
"p5",
"median",
"p95",
"currency"
],
"description": "Asking prices of the listings on sale.",
"properties": {
"p5": {
"type": [
"integer",
"null"
],
"description": "5th percentile asking price, rounded to three significant figures.",
"minimum": 0
},
"median": {
"type": [
"integer",
"null"
],
"description": "Median asking price, rounded to three significant figures.",
"minimum": 0
},
"p95": {
"type": [
"integer",
"null"
],
"description": "95th percentile asking price, rounded to three significant figures.",
"minimum": 0
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
}
}
},
"mileage": {
"type": "object",
"additionalProperties": false,
"required": [
"p5",
"median",
"p95",
"unit"
],
"description": "Mileage of the listings on sale, in the market's unit.",
"properties": {
"p5": {
"type": [
"integer",
"null"
],
"description": "5th percentile mileage, rounded to 1,000 km or mi (100 Scandinavian mil).",
"minimum": 0
},
"median": {
"type": [
"integer",
"null"
],
"description": "Median mileage, rounded the same way.",
"minimum": 0
},
"p95": {
"type": [
"integer",
"null"
],
"description": "95th percentile mileage, rounded the same way.",
"minimum": 0
},
"unit": {
"type": "string",
"enum": [
"km",
"mi",
"mil"
]
}
}
},
"model_years": {
"type": [
"object",
"null"
],
"additionalProperties": false,
"required": [
"most_common",
"from",
"to"
],
"properties": {
"most_common": {
"type": [
"integer",
"null"
],
"description": "The most listed model year.",
"minimum": 1900
},
"from": {
"type": [
"integer",
"null"
],
"description": "Earliest model year of all but the outer 2% of listings.",
"minimum": 1900
},
"to": {
"type": [
"integer",
"null"
],
"description": "Latest model year of all but the outer 2% of listings.",
"minimum": 1900
}
}
},
"price_ratings": {
"type": "object",
"additionalProperties": false,
"required": [
"5",
"4",
"3",
"2",
"1",
"unrated"
],
"description": "Share of listings on sale in each AutoUncle price rating (5 is super price, 1 is expensive), to two decimals.",
"properties": {
"5": {
"type": [
"number",
"null"
],
"minimum": 0,
"maximum": 1,
"description": "Share of listings on sale with price rating 5."
},
"4": {
"type": [
"number",
"null"
],
"minimum": 0,
"maximum": 1,
"description": "Share of listings on sale with price rating 4."
},
"3": {
"type": [
"number",
"null"
],
"minimum": 0,
"maximum": 1,
"description": "Share of listings on sale with price rating 3."
},
"2": {
"type": [
"number",
"null"
],
"minimum": 0,
"maximum": 1,
"description": "Share of listings on sale with price rating 2."
},
"1": {
"type": [
"number",
"null"
],
"minimum": 0,
"maximum": 1,
"description": "Share of listings on sale with price rating 1."
},
"unrated": {
"type": [
"number",
"null"
],
"minimum": 0,
"maximum": 1,
"description": "Share of listings on sale without a price rating."
}
}
},
"share_with_price_drop": {
"type": [
"number",
"null"
],
"minimum": 0,
"maximum": 1,
"description": "Share of listings on sale whose asking price has been lowered."
},
"top_equipment_variants": {
"type": "array",
"maxItems": 3,
"items": {
"type": "string",
"minLength": 1
},
"description": "The three most listed equipment-variant names, most listed first."
}
}
},
"flow": {
"type": [
"object",
"null"
],
"additionalProperties": false,
"required": [
"window_days",
"left_market_per_day",
"new_listings_still_on_sale_per_day"
],
"description": "Pace over the last 30 days. Null when withheld (fewer than 10 listings left the market in the window) or unavailable.",
"properties": {
"window_days": {
"type": "integer",
"const": 30
},
"left_market_per_day": {
"type": [
"number",
"null"
],
"description": "Listings that left the market per day over the window (on sale at least one day). Left the market means removed from sale, usually but not always a sale.",
"minimum": 0
},
"new_listings_still_on_sale_per_day": {
"type": [
"number",
"null"
],
"description": "Listings that went on sale within the window and are still on sale, per day. Listings that came and went within the window are not counted, so this is not total inflow.",
"minimum": 0
}
}
},
"turnover": {
"type": [
"object",
"null"
],
"additionalProperties": false,
"required": [
"window_days",
"median_days_to_leave",
"mean_days_to_leave"
],
"description": "How long listings of this type take to leave the market. Null when withheld or unavailable.",
"properties": {
"window_days": {
"type": "integer",
"const": 60
},
"median_days_to_leave": {
"type": [
"integer",
"null"
],
"description": "Median days from going on sale to leaving the market, for listings that left in the window.",
"minimum": 0
},
"mean_days_to_leave": {
"type": [
"integer",
"null"
],
"description": "Mean of the same.",
"minimum": 0
}
}
},
"demand": {
"type": [
"object",
"null"
],
"additionalProperties": false,
"required": [
"days_of_supply",
"turnovers_per_year",
"relative_to_market",
"level"
],
"description": "Derived demand measures. Null when on_sale or flow is withheld or unavailable.",
"properties": {
"days_of_supply": {
"type": [
"integer",
"null"
],
"description": "Listings on sale ÷ listings leaving the market per day: how long today's stock lasts at the current pace.",
"minimum": 0
},
"turnovers_per_year": {
"type": [
"number",
"null"
],
"description": "12 × listings that left in 30 days ÷ listings on sale.",
"minimum": 0
},
"relative_to_market": {
"type": [
"number",
"null"
],
"description": "days_of_supply ÷ the same measure for the market's whole used-car stock. Below 1 the type moves faster than the market.",
"minimum": 0
},
"level": {
"type": [
"string",
"null"
],
"enum": [
"high",
"average",
"low",
null
],
"description": "high below 0.8 relative_to_market, low above 1.25, otherwise average. Null when the whole market's figures could not be read."
}
}
},
"trend": {
"type": [
"object",
"null"
],
"additionalProperties": false,
"required": [
"months",
"currency",
"series",
"current_month"
],
"description": "The last 12 complete months of listings that left the market. Null when it could not be read (market_trend_unavailable warning).",
"properties": {
"months": {
"type": "integer",
"minimum": 0,
"maximum": 12,
"description": "Complete calendar months in series: 12, or fewer where the store holds less history."
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"series": {
"type": "array",
"maxItems": 12,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"month",
"left_market",
"median_days_to_leave",
"median_last_asking_price",
"suppressed"
],
"properties": {
"month": {
"type": "string",
"pattern": "^[0-9]{4}-[0-9]{2}$"
},
"left_market": {
"type": [
"integer",
"null"
],
"description": "Listings that left the market that month (on sale at least one day).",
"minimum": 0
},
"median_days_to_leave": {
"type": [
"integer",
"null"
],
"description": "Median days from going on sale to leaving the market.",
"minimum": 0
},
"median_last_asking_price": {
"type": [
"integer",
"null"
],
"description": "Median last asking price before leaving the market, rounded to three significant figures. Not a transaction price.",
"minimum": 0
},
"suppressed": {
"type": "boolean",
"description": "True when fewer than 10 listings left the market that month; its figures are then null."
}
}
},
"description": "Oldest month first."
},
"current_month": {
"type": "object",
"additionalProperties": false,
"required": [
"month",
"partial"
],
"description": "The month in progress, which is never in series.",
"properties": {
"month": {
"type": "string",
"pattern": "^[0-9]{4}-[0-9]{2}$"
},
"partial": {
"type": "boolean",
"const": true
}
}
}
}
},
"suppressed": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"section",
"reason"
],
"properties": {
"section": {
"type": "string",
"enum": [
"supply",
"flow",
"turnover",
"demand",
"trend"
]
},
"month": {
"type": "string",
"pattern": "^[0-9]{4}-[0-9]{2}$"
},
"reason": {
"type": "string",
"enum": [
"fewer_than_10_listings"
]
}
}
},
"description": "Every block or trend month withheld because it would be built from fewer than 10 listings."
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$"
},
"message": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false,
"required": [
"code",
"message"
]
}
},
"usage": {
"type": "object",
"properties": {
"billable": {
"type": "boolean"
},
"credits_used": {
"type": "integer",
"minimum": 0,
"maximum": 1
},
"original_credits_used": {
"type": "integer",
"minimum": 0,
"maximum": 1
},
"charges": {
"type": "object",
"properties": {
"base": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": false
},
"credits_remaining": {
"type": "integer",
"minimum": 0
},
"cache_hit": {
"type": "boolean"
},
"idempotent_replay": {
"type": "boolean"
},
"mode": {
"type": "string",
"enum": [
"live",
"test"
]
}
},
"additionalProperties": false,
"required": [
"billable",
"credits_used",
"original_credits_used",
"charges",
"credits_remaining",
"cache_hit",
"idempotent_replay",
"mode"
]
},
"notes": {
"$ref": "#/components/schemas/Notes"
},
"attributions": {
"$ref": "#/components/schemas/Attributions"
}
}
}