{
	"openapi": "3.1.0",
	"info": {
		"title": "Old Cars Data API",
		"version": "1.0.0",
		"description": "Search and analyze 400,000+ classic and collector car auction results from Bring a Trailer, Cars & Bids, Hemmings, AutoHunter, Hagerty, PCAR Market, All Collector Cars, Gooding & Co, RM Sotheby's, Barrett-Jackson, Sotheby's Motorsport, Car & Classic, The Market, Broad Arrow, MB Market, Mecum Auctions, PistonHeads, Collecting Cars, and Bonhams. Data from 2018 to present, refreshed every 15 minutes. Use this API to find what a specific car sold for, get pricing statistics, track market trends, and compare auction results across platforms.",
		"contact": {
			"email": "support@oldcarsdata.com",
			"url": "https://oldcarsdata.com"
		},
		"termsOfService": "https://oldcarsdata.com/terms-of-service"
	},
	"servers": [
		{ "url": "https://api.oldcarsdata.com", "description": "Production" }
	],
	"security": [{ "bearerAuth": [] }],
	"paths": {
		"/makes": {
			"get": {
				"operationId": "listMakes",
				"summary": "List all vehicle makes",
				"description": "List all vehicle makes in the database. Public endpoint, no authentication required. Does not count toward plan query limits. Use these exact strings as the `make` query parameter on GET /auctions. Covers 100+ makes across Bring a Trailer, Cars & Bids, Hemmings, AutoHunter, Hagerty, PCAR Market, All Collector Cars, Gooding & Co, RM Sotheby's, Barrett-Jackson, Sotheby's Motorsport, Car & Classic, The Market, Broad Arrow, MB Market, Mecum Auctions, PistonHeads, Collecting Cars, and Bonhams.",
				"security": [],
				"responses": {
					"200": {
						"description": "List of makes",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"data": {
											"type": "array",
											"items": { "type": "string" },
											"description": "Make names sorted alphabetically"
										}
									}
								}
							}
						}
					},
					"429": { "$ref": "#/components/responses/RateLimited" }
				}
			}
		},
		"/models": {
			"get": {
				"operationId": "listModels",
				"summary": "List models for a make",
				"description": "List all models for a given vehicle make. Public endpoint, no authentication required. Does not count toward plan query limits. Use these exact strings as the `model` query parameter on GET /auctions together with a `make` from GET /makes.",
				"security": [],
				"parameters": [
					{
						"name": "make",
						"in": "query",
						"required": true,
						"schema": { "type": "string", "minLength": 1 },
						"description": "Vehicle make (e.g. \"Porsche\", \"BMW\", \"Toyota\")"
					}
				],
				"responses": {
					"200": {
						"description": "List of models",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"data": {
											"type": "array",
											"items": { "type": "string" },
											"description": "Model names sorted alphabetically"
										}
									}
								}
							}
						}
					},
					"400": { "$ref": "#/components/responses/ValidationError" },
					"429": { "$ref": "#/components/responses/RateLimited" }
				}
			}
		},
		"/auctions": {
			"get": {
				"operationId": "searchAuctions",
				"summary": "Search auction results",
				"description": "Search completed classic and collector car auction results. Counts toward plan query limits. All filters are optional. Use `make` and `model` for normalized vehicle filtering, `vin` for exact raw VIN lookup, `seller_username` for exact seller lookup, or combine other filters such as `status`, `source`, `keyword`, year bounds, and price bounds. For large or sequential result sets, use `pagination=cursor`: it avoids exact count and deep-offset work and returns an opaque `next_cursor` for the following request.",
				"parameters": [
					{
						"name": "make",
						"in": "query",
						"required": false,
						"schema": { "type": "string", "minLength": 1 },
						"description": "Exact make name from GET /makes (e.g. \"Toyota\"). Optional."
					},
					{
						"name": "vin",
						"in": "query",
						"required": false,
						"schema": { "type": "string", "minLength": 1 },
						"description": "Exact VIN match (raw string, case-sensitive as stored). When set, `make` is not required."
					},
					{
						"name": "seller_username",
						"in": "query",
						"required": false,
						"schema": { "type": "string", "minLength": 1 },
						"description": "Exact seller username match. When set alone or with `vin`, `make` is not required."
					},
					{
						"name": "model",
						"in": "query",
						"schema": { "type": "string" },
						"description": "Exact model name as returned by GET /models for this make (e.g. \"Land Cruiser\")"
					},
					{
						"name": "year_min",
						"in": "query",
						"schema": { "type": "integer" },
						"description": "Minimum model year (inclusive)"
					},
					{
						"name": "year_max",
						"in": "query",
						"schema": { "type": "integer" },
						"description": "Maximum model year (inclusive)"
					},
					{
						"name": "price_min",
						"in": "query",
						"schema": { "type": "integer" },
						"description": "Minimum sale price (inclusive)"
					},
					{
						"name": "price_max",
						"in": "query",
						"schema": { "type": "integer" },
						"description": "Maximum sale price (inclusive)"
					},
					{
						"name": "status",
						"in": "query",
						"schema": {
							"type": "string",
							"enum": [
								"sold",
								"unsold",
								"result unavailable",
								"reserve not met",
								"canceled",
								"unknown",
								"withdrawn"
							]
						},
						"description": "Auction outcome status. `unsold` includes every completed outcome except `sold`."
					},
					{
						"name": "source",
						"in": "query",
						"schema": { "type": "string" },
						"description": "Source platform (for example \"bringatrailer\", \"barrettjackson\", \"carandclassic\", \"mecum\", or \"bonhams\")"
					},
					{
						"name": "keyword",
						"in": "query",
						"schema": { "type": "string" },
						"description": "Search in title and description (case-insensitive)"
					},
					{
						"name": "sort",
						"in": "query",
						"schema": {
							"type": "string",
							"enum": ["date", "price", "year", "bids"],
							"default": "date"
						},
						"description": "Sort field. `date` orders by `auction_end_at`; date-precision values use their normalized 00:00:00 placeholder."
					},
					{
						"name": "direction",
						"in": "query",
						"schema": {
							"type": "string",
							"enum": ["asc", "desc"],
							"default": "desc"
						},
						"description": "Sort direction"
					},
					{
						"name": "pagination",
						"in": "query",
						"schema": {
							"type": "string",
							"enum": ["page", "cursor"],
							"default": "page"
						},
						"description": "Pagination mode. Deprecated `page` mode preserves the legacy exact-count response. `cursor` supports `sort=date`, skips exact counts and offsets, and returns `next_cursor`."
					},
					{
						"name": "cursor",
						"in": "query",
						"schema": { "type": "string" },
						"description": "Opaque cursor from the previous cursor response. Repeat the same filters, sort, and direction. Omit on the first `pagination=cursor` request. The traversal expires 24 hours after its first cursor is issued. Cursor traversal reads the live completed-auction dataset rather than a materialized snapshot; records changed between requests can repeat or be omitted. De-duplicate by auction `id`, and do not treat a live traversal as a complete point-in-time export."
					},
					{
						"name": "page",
						"in": "query",
						"deprecated": true,
						"schema": { "type": "integer", "minimum": 1, "default": 1 },
						"description": "Deprecated page number for legacy `pagination=page`. Use cursor pagination for sequential traversal. If supplied with cursor pagination, it must be 1 and is ignored."
					},
					{
						"name": "limit",
						"in": "query",
						"schema": {
							"type": "integer",
							"minimum": 1,
							"maximum": 100,
							"default": 50
						},
						"description": "Results per page"
					}
				],
				"responses": {
					"200": {
						"description": "Page- or cursor-paginated auction results",
						"headers": {
							"Deprecation": {
								"description": "RFC 9745 deprecation date, returned when the legacy page representation is used.",
								"schema": { "type": "string", "example": "@1787011200" }
							},
							"Link": {
								"description": "Migration documentation with rel=deprecation.",
								"schema": { "type": "string" }
							}
						},
						"content": {
							"application/json": {
								"schema": { "$ref": "#/components/schemas/AuctionsResponse" }
							}
						}
					},
					"400": { "$ref": "#/components/responses/ValidationError" },
					"401": { "$ref": "#/components/responses/Unauthorized" },
					"403": { "$ref": "#/components/responses/EmailVerificationRequired" },
					"429": { "$ref": "#/components/responses/RateLimited" },
					"504": {
						"description": "The database query exceeded the processing deadline",
						"headers": {
							"Retry-After": {
								"description": "Seconds to wait before retrying the auction query",
								"schema": { "type": "integer", "minimum": 1, "example": 5 }
							}
						},
						"content": {
							"application/json": {
								"schema": { "$ref": "#/components/schemas/Error" },
								"example": {
									"error": "Gateway Timeout",
									"code": "auction_query_timeout",
									"message": "The query exceeded the processing deadline. Narrow the filters or retry after 5 seconds."
								}
							}
						}
					}
				}
			}
		},
		"/auctions/live": {
			"get": {
				"operationId": "listLiveAuctions",
				"summary": "List live auctions",
				"description": "List currently active collector car auctions. No filters are required. Optional filters can narrow by make, model, VIN, seller, source, keyword, year/price bounds, auction ending window, or records updated since a timestamp. Counts toward plan query limits.",
				"parameters": [
					{
						"name": "make",
						"in": "query",
						"required": false,
						"schema": { "type": "string", "minLength": 1 },
						"description": "Exact normalized make name from GET /makes."
					},
					{
						"name": "model",
						"in": "query",
						"schema": { "type": "string" },
						"description": "Exact normalized model name from GET /models."
					},
					{
						"name": "vin",
						"in": "query",
						"required": false,
						"schema": { "type": "string", "minLength": 1 },
						"description": "Exact VIN match."
					},
					{
						"name": "seller_username",
						"in": "query",
						"required": false,
						"schema": { "type": "string", "minLength": 1 },
						"description": "Exact seller username match."
					},
					{
						"name": "year_min",
						"in": "query",
						"schema": { "type": "integer" },
						"description": "Minimum model year (inclusive)"
					},
					{
						"name": "year_max",
						"in": "query",
						"schema": { "type": "integer" },
						"description": "Maximum model year (inclusive)"
					},
					{
						"name": "price_min",
						"in": "query",
						"schema": { "type": "integer" },
						"description": "Minimum current bid or listed price (inclusive)"
					},
					{
						"name": "price_max",
						"in": "query",
						"schema": { "type": "integer" },
						"description": "Maximum current bid or listed price (inclusive)"
					},
					{
						"name": "source",
						"in": "query",
						"schema": { "type": "string" },
						"description": "Source platform. Supported live values include \"bringatrailer\", \"carsandbids\", \"hemmings\", \"hagerty\", \"pcarmarket\", \"acc\", \"gooding\", \"rmsothebys\", \"sothebysmotorsport\", \"carandclassic\", \"themarket\", \"mbmarket\", \"mecum\", and \"pistonheads\"."
					},
					{
						"name": "keyword",
						"in": "query",
						"schema": { "type": "string" },
						"description": "Search in title and description (case-insensitive)"
					},
					{
						"name": "ending_after",
						"in": "query",
						"schema": { "type": "string", "format": "date-time" },
						"description": "Only include auctions ending at or after this time."
					},
					{
						"name": "ending_before",
						"in": "query",
						"schema": { "type": "string", "format": "date-time" },
						"description": "Only include auctions ending at or before this time."
					},
					{
						"name": "updated_since",
						"in": "query",
						"schema": { "type": "string", "format": "date-time" },
						"description": "Only include auctions updated at or after this timestamp. Useful for polling."
					},
					{
						"name": "sort",
						"in": "query",
						"schema": {
							"type": "string",
							"enum": ["ending", "created", "updated", "price", "year", "bids"],
							"default": "ending"
						},
						"description": "Sort field"
					},
					{
						"name": "direction",
						"in": "query",
						"schema": {
							"type": "string",
							"enum": ["asc", "desc"],
							"default": "asc"
						},
						"description": "Sort direction"
					},
					{
						"name": "page",
						"in": "query",
						"schema": { "type": "integer", "minimum": 1, "default": 1 },
						"description": "Page number"
					},
					{
						"name": "limit",
						"in": "query",
						"schema": {
							"type": "integer",
							"minimum": 1,
							"maximum": 100,
							"default": 50
						},
						"description": "Results per page"
					}
				],
				"responses": {
					"200": {
						"description": "Paginated live auction results",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/LiveAuctionsResponse"
								}
							}
						}
					},
					"400": { "$ref": "#/components/responses/ValidationError" },
					"401": { "$ref": "#/components/responses/Unauthorized" },
					"403": { "$ref": "#/components/responses/EmailVerificationRequired" },
					"429": { "$ref": "#/components/responses/RateLimited" }
				}
			}
		},
		"/auctions/{auction_id}/bids": {
			"get": {
				"operationId": "listAuctionBids",
				"summary": "List auction bid history",
				"description": "List the bid history for a live or completed Bring a Trailer, Cars & Bids, Hemmings, Hagerty, PCAR Market, All Collector Cars, or Sotheby's Motorsport auction where bid data is available. Use the `id` returned by GET /auctions or GET /auctions/live as `auction_id`. Counts toward plan query limits.",
				"parameters": [
					{
						"name": "auction_id",
						"in": "path",
						"required": true,
						"schema": { "type": "integer", "minimum": 1 },
						"description": "Auction ID returned by the auctions endpoints. Bid history is available for supported Bring a Trailer, Cars & Bids, Hemmings, Hagerty, PCAR Market, All Collector Cars, and Sotheby's Motorsport auctions."
					},
					{
						"name": "bid_after",
						"in": "query",
						"schema": { "type": "string", "format": "date-time" },
						"description": "Only include bids placed at or after this time."
					},
					{
						"name": "bid_before",
						"in": "query",
						"schema": { "type": "string", "format": "date-time" },
						"description": "Only include bids placed at or before this time."
					},
					{
						"name": "sort",
						"in": "query",
						"schema": {
							"type": "string",
							"enum": ["bid_at", "amount", "created"],
							"default": "bid_at"
						},
						"description": "Sort field"
					},
					{
						"name": "direction",
						"in": "query",
						"schema": {
							"type": "string",
							"enum": ["asc", "desc"],
							"default": "asc"
						},
						"description": "Sort direction"
					},
					{
						"name": "page",
						"in": "query",
						"schema": { "type": "integer", "minimum": 1, "default": 1 },
						"description": "Page number"
					},
					{
						"name": "limit",
						"in": "query",
						"schema": {
							"type": "integer",
							"minimum": 1,
							"maximum": 100,
							"default": 100
						},
						"description": "Results per page"
					}
				],
				"responses": {
					"200": {
						"description": "Paginated auction bid history",
						"content": {
							"application/json": {
								"schema": { "$ref": "#/components/schemas/AuctionBidsResponse" }
							}
						}
					},
					"400": { "$ref": "#/components/responses/ValidationError" },
					"401": { "$ref": "#/components/responses/Unauthorized" },
					"403": { "$ref": "#/components/responses/EmailVerificationRequired" },
					"429": { "$ref": "#/components/responses/RateLimited" }
				}
			}
		},
		"/stats": {
			"get": {
				"operationId": "getStats",
				"summary": "Get pricing statistics and market trends",
				"description": "Get pricing statistics and 12-month market trends for a vehicle make or make/model. Includes average, median, low/high prices, sell-through rate, and monthly trend data. Requires a paid plan.",
				"parameters": [
					{
						"name": "make",
						"in": "query",
						"required": true,
						"schema": { "type": "string", "minLength": 1 },
						"description": "Vehicle make (e.g. \"Porsche\")"
					},
					{
						"name": "model",
						"in": "query",
						"schema": { "type": "string" },
						"description": "Optional vehicle model (e.g. \"911\")"
					},
					{
						"name": "year_min",
						"in": "query",
						"schema": { "type": "integer" },
						"description": "Minimum model year (inclusive)"
					},
					{
						"name": "year_max",
						"in": "query",
						"schema": { "type": "integer" },
						"description": "Maximum model year (inclusive)"
					}
				],
				"responses": {
					"200": {
						"description": "Pricing statistics",
						"content": {
							"application/json": {
								"schema": { "$ref": "#/components/schemas/StatsResponse" }
							}
						}
					},
					"400": { "$ref": "#/components/responses/ValidationError" },
					"401": { "$ref": "#/components/responses/Unauthorized" },
					"403": {
						"description": "Email verification or paid plan required",
						"content": {
							"application/json": {
								"schema": { "$ref": "#/components/schemas/Error" },
								"example": {
									"error": "Forbidden",
									"message": "The stats endpoint is not available on the free plan. Please upgrade to access this feature."
								}
							}
						}
					},
					"429": { "$ref": "#/components/responses/RateLimited" }
				}
			}
		}
	},
	"components": {
		"securitySchemes": {
			"bearerAuth": {
				"type": "http",
				"scheme": "bearer",
				"description": "API key as Bearer token. Get one at https://oldcarsdata.com/login"
			}
		},
		"schemas": {
			"Auction": {
				"type": "object",
				"properties": {
					"id": { "type": "integer", "nullable": true },
					"source": {
						"type": "string",
						"nullable": true,
						"description": "Platform: \"bringatrailer\", \"carsandbids\", \"hemmings\", \"autohunter\", \"hagerty\", \"pcarmarket\", \"acc\", \"gooding\", \"rmsothebys\", \"barrettjackson\", \"sothebysmotorsport\", \"carandclassic\", \"themarket\", \"broadarrow\", \"mbmarket\", \"mecum\", \"pistonheads\", \"collectingcars\", \"bonhams\""
					},
					"url": {
						"type": "string",
						"nullable": true,
						"description": "Link to original listing"
					},
					"title": { "type": "string", "nullable": true },
					"auction_status": {
						"type": "string",
						"nullable": true,
						"enum": [
							"sold",
							"result unavailable",
							"reserve not met",
							"canceled",
							"unknown",
							"active",
							"withdrawn"
						]
					},
					"price": {
						"type": "number",
						"nullable": true,
						"description": "Amount captured from the source listing. For sold records, this is the source-published sale result; for other outcomes, it may be the highest bid. Old Cars Data does not add buyer premiums, taxes, or fees during normalization, but a source may publish a result that already includes them. Premium treatment is not normalized or identified by a public field; use source and url to verify the convention when it matters."
					},
					"currency": {
						"type": "string",
						"nullable": true,
						"description": "ISO 4217 currency code (e.g. \"USD\", \"CAD\", \"EUR\")"
					},
					"auction_end_date": {
						"type": "string",
						"nullable": true,
						"deprecated": true,
						"description": "Deprecated date-only auction ending value in YYYY-MM-DD format. Use auction_end_at together with auction_end_precision."
					},
					"auction_end_at": {
						"type": "string",
						"nullable": true,
						"description": "Timezone-naive auction ending wall-clock value in YYYY-MM-DD HH:mm:ss[.ffffff] format when available. No source or venue timezone is identified or guaranteed; do not append Z, assume UTC, or treat it as an unambiguous instant. Consult auction_end_precision before interpreting the time component."
					},
					"auction_end_precision": {
						"type": "string",
						"nullable": true,
						"enum": ["exact", "date"],
						"description": "Granularity of auction_end_at. exact means the time-of-day was captured, not that the value is a timezone-aware instant. date means only the calendar date is known and the 00:00:00 time is a normalization placeholder, not a known midnight ending. Null means no ending value is known."
					},
					"mileage": { "type": "number", "nullable": true },
					"mileage_unit": {
						"type": "string",
						"nullable": true,
						"enum": ["mi", "km"],
						"description": "Unit for mileage when known"
					},
					"vin": { "type": "string", "nullable": true },
					"title_status": {
						"type": "string",
						"nullable": true,
						"description": "e.g. \"clean\", \"salvage\""
					},
					"city": { "type": "string", "nullable": true },
					"state": { "type": "string", "nullable": true },
					"zip": { "type": "string", "nullable": true },
					"country_code": {
						"type": "string",
						"nullable": true,
						"description": "ISO 3166-1 alpha-2 country code"
					},
					"seller_username": { "type": "string", "nullable": true },
					"year": { "type": "integer", "nullable": true },
					"has_reserve": { "type": "boolean", "nullable": true },
					"listing_make": { "type": "string", "nullable": true },
					"listing_model": { "type": "string", "nullable": true },
					"ocd_make_name": {
						"type": "string",
						"nullable": true,
						"description": "Normalized make name"
					},
					"ocd_model_name": {
						"type": "string",
						"nullable": true,
						"description": "Normalized model name"
					},
					"engine": { "type": "string", "nullable": true },
					"drivetrain": { "type": "string", "nullable": true },
					"transmission": { "type": "string", "nullable": true },
					"body_style": { "type": "string", "nullable": true },
					"exterior_color": { "type": "string", "nullable": true },
					"standard_exterior_color": { "type": "string", "nullable": true },
					"interior_color": { "type": "string", "nullable": true },
					"standard_interior_color": { "type": "string", "nullable": true },
					"seller_type": {
						"type": "string",
						"nullable": true,
						"description": "\"private\" or \"dealer\""
					},
					"description": { "type": "string", "nullable": true },
					"ownership_history": { "type": "string", "nullable": true },
					"modifications": { "type": "array", "items": { "type": "string" } },
					"known_flaws": { "type": "array", "items": { "type": "string" } },
					"recent_service_history": {
						"type": "array",
						"items": { "type": "string" }
					},
					"listing_details": { "type": "array", "items": { "type": "string" } },
					"created_at": {
						"type": "string",
						"nullable": true,
						"description": "Record creation wall-clock timestamp in YYYY-MM-DD HH:mm:ss[.ffffff] format; no UTC offset is included"
					},
					"featured_image_url": { "type": "string", "nullable": true },
					"stats": {
						"type": "object",
						"properties": {
							"views": { "type": "integer", "nullable": true },
							"watches": { "type": "integer", "nullable": true },
							"likes": { "type": "integer", "nullable": true },
							"bids": { "type": "integer", "nullable": true },
							"unique_bidder_count": {
								"type": "integer",
								"nullable": true,
								"description": "Number of distinct bidders observed for the auction"
							}
						}
					}
				}
			},
			"AuctionsResponse": {
				"type": "object",
				"properties": {
					"data": {
						"type": "array",
						"items": { "$ref": "#/components/schemas/Auction" }
					},
					"meta": {
						"oneOf": [
							{
								"type": "object",
								"required": ["total", "page", "limit", "total_pages"],
								"properties": {
									"total": { "type": "integer" },
									"page": { "type": "integer" },
									"limit": { "type": "integer" },
									"total_pages": { "type": "integer" }
								}
							},
							{
								"type": "object",
								"required": ["pagination", "limit", "has_more", "next_cursor"],
								"properties": {
									"pagination": { "type": "string", "const": "cursor" },
									"limit": { "type": "integer" },
									"has_more": { "type": "boolean" },
									"next_cursor": { "type": "string", "nullable": true }
								}
							}
						]
					}
				}
			},
			"LiveAuction": {
				"allOf": [
					{ "$ref": "#/components/schemas/Auction" },
					{
						"type": "object",
						"properties": {
							"image_url": {
								"type": "string",
								"nullable": true,
								"deprecated": true,
								"description": "Deprecated alias for featured_image_url. Use featured_image_url for new integrations."
							},
							"updated_at": {
								"type": "string",
								"nullable": true,
								"description": "Last-updated wall-clock timestamp in YYYY-MM-DD HH:mm:ss[.ffffff] format; no UTC offset is included"
							}
						}
					}
				]
			},
			"LiveAuctionsResponse": {
				"type": "object",
				"properties": {
					"data": {
						"type": "array",
						"items": { "$ref": "#/components/schemas/LiveAuction" }
					},
					"meta": {
						"type": "object",
						"properties": {
							"total": { "type": "integer" },
							"page": { "type": "integer" },
							"limit": { "type": "integer" },
							"total_pages": { "type": "integer" }
						}
					}
				}
			},
			"Bid": {
				"type": "object",
				"properties": {
					"id": { "type": "integer", "nullable": true },
					"auction_id": {
						"type": "integer",
						"nullable": true,
						"description": "Auction ID from GET /auctions or GET /auctions/live"
					},
					"bidder_name": { "type": "string", "nullable": true },
					"amount": {
						"type": "integer",
						"nullable": true,
						"description": "Bid amount"
					},
					"currency": {
						"type": "string",
						"nullable": true,
						"description": "ISO 4217 currency code (e.g. \"USD\", \"CAD\", \"EUR\")"
					},
					"bid_at": {
						"type": "string",
						"nullable": true,
						"description": "Bid placement wall-clock timestamp in YYYY-MM-DD HH:mm:ss[.ffffff] format when available; no UTC offset is included"
					},
					"created_at": {
						"type": "string",
						"nullable": true,
						"description": "Record creation wall-clock timestamp in YYYY-MM-DD HH:mm:ss[.ffffff] format; no UTC offset is included"
					}
				}
			},
			"AuctionBidsResponse": {
				"type": "object",
				"properties": {
					"data": {
						"type": "array",
						"items": { "$ref": "#/components/schemas/Bid" }
					},
					"meta": {
						"type": "object",
						"properties": {
							"total": { "type": "integer" },
							"page": { "type": "integer" },
							"limit": { "type": "integer" },
							"total_pages": { "type": "integer" }
						}
					}
				}
			},
			"StatsResponse": {
				"type": "object",
				"properties": {
					"currency": {
						"type": "string",
						"description": "ISO 4217 currency code for all price values"
					},
					"total_sales": {
						"type": "integer",
						"description": "Total sold auctions"
					},
					"average_price": {
						"type": "number",
						"description": "Average sale price"
					},
					"median_price": {
						"type": "number",
						"description": "Median sale price"
					},
					"lowest_price": { "type": "number" },
					"highest_price": { "type": "number" },
					"sell_through_rate": {
						"type": "number",
						"description": "Ratio of sold to total auctions (0.0-1.0)"
					},
					"price_trend": {
						"type": "array",
						"description": "Monthly data for the current calendar month and preceding 11 calendar months; future-dated auctions are excluded",
						"items": {
							"type": "object",
							"properties": {
								"date": { "type": "string", "description": "YYYY-MM" },
								"avg_price": { "type": "number" },
								"volume": { "type": "integer" }
							}
						}
					}
				}
			},
			"Error": {
				"type": "object",
				"properties": {
					"error": { "type": "string" },
					"code": {
						"type": "string",
						"description": "Optional stable machine-readable error code"
					},
					"message": { "type": "string" },
					"details": {
						"type": "object",
						"description": "Field-level validation errors (400 only)"
					}
				}
			}
		},
		"responses": {
			"ValidationError": {
				"description": "Validation error",
				"content": {
					"application/json": {
						"schema": { "$ref": "#/components/schemas/Error" },
						"example": {
							"error": "Validation Error",
							"message": "limit: Number must be less than or equal to 100",
							"details": {
								"limit": ["Number must be less than or equal to 100"]
							}
						}
					}
				}
			},
			"Unauthorized": {
				"description": "Missing or invalid API key. REST authentication errors wrap the underlying error object as a JSON string in `message`.",
				"content": {
					"application/json": {
						"schema": { "$ref": "#/components/schemas/Error" },
						"example": {
							"error": "HTTP Error",
							"message": "{\"error\":\"Unauthorized\",\"message\":\"API key is required. Provide it via Authorization: Bearer <key> header\"}"
						}
					}
				}
			},
			"EmailVerificationRequired": {
				"description": "Email verification required for a non-paying account",
				"content": {
					"application/json": {
						"schema": { "$ref": "#/components/schemas/Error" },
						"example": {
							"error": "Email Verification Required",
							"message": "Verify your email before using the API."
						}
					}
				}
			},
			"RateLimited": {
				"description": "The rolling per-minute burst limit, billing-period plan quota, or temporary auction-query capacity was exceeded",
				"headers": {
					"Retry-After": {
						"description": "Seconds to wait before retrying",
						"schema": { "type": "integer", "minimum": 1 }
					},
					"X-BurstRateLimit-Limit": {
						"description": "Requests allowed in the rolling 60-second window",
						"schema": { "type": "integer", "example": 250 }
					},
					"X-BurstRateLimit-Remaining": {
						"description": "Requests remaining in the rolling window",
						"schema": { "type": "integer", "example": 0 }
					},
					"X-BurstRateLimit-Reset": {
						"description": "Unix timestamp when request capacity becomes available",
						"schema": { "type": "integer" }
					}
				},
				"content": {
					"application/json": {
						"schema": { "$ref": "#/components/schemas/Error" },
						"example": {
							"error": "Rate Limit Exceeded",
							"message": "Too many requests. Limit is 250 requests per minute."
						}
					}
				}
			}
		}
	}
}