{"openapi":"3.1.0","info":{"title":"CLCAuto Public API","version":"0.1.0","description":"Public API of 常來車網 (clcauto.com), a non-profit, multilingual used-car marketplace in North America.\n\n**Auth.** `Authorization: Bearer clc_live_...`. Create keys at https://www.clcauto.com/zh/developers/keys. Read endpoints also work without a key at stricter limits; write endpoints always need a key with the matching scope.\n\n**Quota.** Write quota is per account (all keys share it), reset daily at 00:00 UTC. Personal tier: 10 new listings + 30 updates per day. Dealer tier (account with a verified store): 2000 writes per day, 500 active listings. Every write response carries `X-Quota-Inserts-Remaining` / `X-Quota-Updates-Remaining`.\n\n**Keys.** Up to 5 active keys per account. Scopes: `read:cars`, `read:dealers`, `write:inventory`, `write:images`. Key management itself is done in the web portal (session auth), not through this API.\n\n**Languages.** Send listing text in any language; it is stored verbatim and machine-translated into the other site languages (zh, en, ko, ja, es, fr) in the background. Reads return text in `lang` once translated, plus the original (`description_original`, `features_original`).\n\n**Errors.** Always `{ \"error\": { \"code\", \"message\", \"details?\" } }`. CORS is open (`*`).","contact":{"name":"CLCAuto","url":"https://www.clcauto.com/zh/contact"}},"servers":[{"url":"https://www.clcauto.com/api/v1"}],"tags":[{"name":"Cars","description":"Public read access to active listings."},{"name":"Dealers","description":"Verified dealer stores."},{"name":"Meta","description":"Aggregates and this spec."},{"name":"Inventory","description":"Manage your own listings with an API key."}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"clc_live_...","description":"API key created in the developer portal, sent as a bearer token."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["bad_request","validation_failed","unauthorized","key_revoked","key_expired","ip_not_allowed","insufficient_scope","forbidden","account_banned","not_found","conflict","listing_blocked","rate_limited","quota_exceeded","internal_error"]},"message":{"type":"string"},"details":{"type":"array","description":"Present on `validation_failed`.","items":{"type":"object","required":["field","issue"],"properties":{"field":{"type":"string"},"issue":{"type":"string"}}}},"quota":{"$ref":"#/components/schemas/Quota","description":"Present on `quota_exceeded`."},"existing_id":{"type":"string","format":"uuid","description":"Present on `conflict` when a listing with the same VIN already exists under this account. Retry with `?adopt=true` to attach the external_id to it."}}}}},"Quota":{"type":"object","description":"Daily write quota of the key owner (all keys of one account share it). Day boundary is UTC.","required":["tier","inserts_used","inserts_limit","updates_used","updates_limit","writes_limit","active_used","active_limit","resets_at"],"properties":{"tier":{"type":"string","enum":["anonymous","personal","dealer"]},"inserts_used":{"type":"integer"},"inserts_limit":{"type":"integer"},"updates_used":{"type":"integer"},"updates_limit":{"type":"integer"},"writes_limit":{"type":["integer","null"],"description":"Dealer tier: combined insert+update cap. `null` on personal tier."},"active_used":{"type":"integer"},"active_limit":{"type":["integer","null"],"description":"Max active listings (dealer tier); `null` = same as manual posting."},"resets_at":{"type":"string","format":"date-time"}}},"EnumValue":{"type":"object","required":["value","label"],"properties":{"value":{"type":["string","null"]},"label":{"type":["string","null"]}}},"Seller":{"type":"object","required":["id","username","account_type","is_system","languages"],"properties":{"id":{"type":"string","format":"uuid","description":"Profile id; use as `seller_id` filter on `/cars`."},"username":{"type":["string","null"]},"account_type":{"type":"string","enum":["private","dealer"]},"is_system":{"type":"boolean","description":"`true` = system account that republishes a dealer's public inventory."},"languages":{"type":"array","items":{"type":"string"},"description":"ISO-639-1 codes the seller can communicate in."}}},"ContactApps":{"type":"object","description":"Messenger accounts the seller chose to publish (opt-in; never derived from other fields). Only filled keys are present; `{}` when none. `whatsapp` is E.164 (`+16265550123`, open as `https://wa.me/<digits>`); `wechat` / `kakao` / `line` are IDs matching `^[A-Za-z0-9._-]{1,32}$` (LINE: `https://line.me/ti/p/~<id>`). SMS uses the seller `phone`.","additionalProperties":false,"properties":{"wechat":{"type":"string","pattern":"^[A-Za-z0-9._-]{1,32}$"},"kakao":{"type":"string","pattern":"^[A-Za-z0-9._-]{1,32}$"},"line":{"type":"string","pattern":"^[A-Za-z0-9._-]{1,32}$"},"whatsapp":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"}}},"Store":{"type":"object","required":["id","name","address","lat","lng","phone","wechat"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"address":{"type":"string"},"lat":{"type":["number","null"]},"lng":{"type":["number","null"]},"phone":{"type":["string","null"],"description":"`null` for anonymous requests."},"wechat":{"type":["string","null"],"description":"`null` for anonymous requests."}}},"CarSummary":{"type":"object","required":["id","url","title","year","make","model","trim","price","original_price","currency","mileage","mileage_unit","location","country","image_url","fuel_type","transmission","drivetrain","exterior_color","interior_color","status","is_syndicated","seller","created_at","updated_at","expires_at"],"properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri","description":"Public listing page in the requested `lang`."},"title":{"type":"string","description":"Localized by `lang`."},"year":{"type":"integer"},"make":{"type":"string"},"model":{"type":"string"},"trim":{"type":["string","null"]},"price":{"type":"integer","description":"Whole units of `currency`. `0` = call for price."},"original_price":{"type":["integer","null"],"description":"Same currency as `price`."},"price_updated_at":{"type":["string","null"],"format":"date-time"},"currency":{"type":"string","enum":["USD","CAD","AUD","NZD"],"description":"Currency of `price` / `original_price`: `USD` (default), `CAD` (Canada), `AUD` (Australia) or `NZD` (New Zealand)."},"mileage":{"type":"integer","description":"Odometer reading in `mileage_unit`."},"mileage_unit":{"type":"string","enum":["mi","km"],"description":"Unit of `mileage`: `mi` (default) or `km`."},"location":{"type":"object","required":["name","lat","lng"],"properties":{"name":{"type":"string","description":"City, State — localized by `lang`."},"lat":{"type":["number","null"]},"lng":{"type":["number","null"]}}},"country":{"type":"string","enum":["US","CA","AU","NZ"],"description":"Country of the car: `US`, `CA`, `AU` or `NZ`. Derived, not stored: inferred from the coordinates, then the location text (country / state names), then the postcode format; `US` when nothing tells."},"image_url":{"type":["string","null"],"format":"uri","description":"Cover image."},"fuel_type":{"type":"object","required":["value","label"],"description":"Fuel type.","properties":{"value":{"type":["string","null"],"enum":["gasoline","diesel","electric","hybrid","phev","hydrogen",null],"description":"`gasoline` = Gas, `diesel` = Diesel, `electric` = Electric, `hybrid` = Hybrid, `phev` = Plug-in hybrid, `hydrogen` = Hydrogen fuel cell"},"label":{"type":["string","null"]}}},"transmission":{"type":"object","required":["value","label"],"description":"Transmission.","properties":{"value":{"type":["string","null"],"enum":["automatic","manual","cvt","dct","amt","single_speed",null],"description":"`automatic` = Automatic (AT), `manual` = Manual (MT), `cvt` = CVT, `dct` = DCT (Dual-Clutch), `amt` = AMT (Automated Manual), `single_speed` = Single-Speed (EV)"},"label":{"type":["string","null"]}}},"drivetrain":{"type":"object","required":["value","label"],"description":"Drivetrain.","properties":{"value":{"type":["string","null"],"enum":["fwd","rwd","awd","4wd",null],"description":"`fwd` = FWD, `rwd` = RWD, `awd` = AWD, `4wd` = 4WD"},"label":{"type":["string","null"]}}},"exterior_color":{"$ref":"#/components/schemas/EnumValue","description":"`value` is the stored text (may be Chinese), `label` is localized."},"interior_color":{"$ref":"#/components/schemas/EnumValue","description":"`value` is the stored text (may be Chinese), `label` is localized."},"status":{"type":["string","null"],"enum":["active","pending","sold","removed",null]},"is_syndicated":{"type":"boolean","description":"`true` = republished from a dealer website by a system account; API-uploaded and manual listings are `false`."},"seller":{"$ref":"#/components/schemas/Seller"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time","description":"Last change to the listing's visible content: description, features, year, make, model, trim, price, original_price, mileage, photos, status and visibility, colors, fuel type, transmission, drivetrain, location and coordinates, carfax_url, carfax_summary, VIN, source_url, seller phone. View counts, favorites, translation updates and seller profile edits don't move it."},"expires_at":{"type":["string","null"],"format":"date-time"}}},"CarDetail":{"allOf":[{"$ref":"#/components/schemas/CarSummary"},{"type":"object","required":["description","description_original","description_lang","description_translated","features","features_original","images","title_status","condition","vin","views_count","favorites_count","seller"],"properties":{"description":{"type":"string","description":"Description in the requested `lang`: the machine translation once it is ready (`description_translated: true`), otherwise the seller's original text. Empty string when the listing has no description."},"description_original":{"type":["string","null"],"description":"The seller's own description, verbatim, in whatever language it was written. `null` when there is none."},"description_lang":{"type":["string","null"],"description":"ISO 639-1 code of the language `description_original` is written in (e.g. `en`, `zh`, `es`). `null` until language detection has run, and when the language can't be determined (e.g. only model names and numbers) or isn't one we recognize."},"description_translated":{"type":"boolean","description":"`true` when `description` is a machine translation into `lang`."},"features":{"type":"array","items":{"type":"string"},"description":"Feature tags in the requested `lang`; the same feature written in several languages is listed once. Unrecognized tags are returned as written."},"features_original":{"type":"array","items":{"type":"string"},"description":"Feature tags exactly as the seller sent them."},"images":{"type":"array","items":{"type":"string","format":"uri"}},"title_status":{"type":"object","required":["value","label"],"description":"Title brand as declared by the seller (dealer listings: only when the source text says it explicitly). `value` is `null` when not provided — that does not mean clean.","properties":{"value":{"type":["string","null"],"enum":["clean","rebuilt","salvage","lemon_buyback","ppsr_clear","written_off",null],"description":"`clean` = Clean title, `rebuilt` = Rebuilt title, `salvage` = Salvage title, `lemon_buyback` = Lemon buyback, `ppsr_clear` = No money owing (PPSR checked), `written_off` = Written-off"},"label":{"type":["string","null"]}}},"condition":{"$ref":"#/components/schemas/Condition"},"vin":{"type":["string","null"],"description":"Anonymous requests get a masked VIN (`1HGCV1F3****2345`); keyed requests get the full VIN."},"carfax_url":{"type":["string","null"],"format":"uri"},"carfax_summary":{"type":["string","null"],"description":"Short Carfax summary (owners, accidents, service records) in the requested `lang`."},"views_count":{"type":"integer"},"favorites_count":{"type":"integer"},"source_url":{"type":["string","null"],"format":"uri","description":"Original page when `is_syndicated`."},"seller":{"allOf":[{"$ref":"#/components/schemas/Seller"},{"type":"object","required":["phone","contact_apps","store"],"properties":{"phone":{"type":["string","null"],"description":"`null` for anonymous requests."},"contact_apps":{"oneOf":[{"$ref":"#/components/schemas/ContactApps"},{"type":"null"}],"description":"`null` for anonymous requests."},"store":{"oneOf":[{"$ref":"#/components/schemas/Store"},{"type":"null"}],"description":"First verified store of a dealer seller; `null` for individuals."}}}]}}}]},"Condition":{"type":"object","description":"Structured condition checklist as declared by the seller. Every item is optional: `null` = not provided (it does not mean \"no\"). Fixed values only — sellers explain details in `description`. Changes to the checklist don't move `updated_at`.","required":["service_records","one_owner","smoker","keys_count","tires_condition","known_issues"],"properties":{"service_records":{"type":["boolean","null"],"description":"Service records available."},"one_owner":{"type":["boolean","null"],"description":"One-owner vehicle."},"smoker":{"type":["boolean","null"],"description":"Smoked in."},"keys_count":{"type":["integer","null"],"minimum":0,"maximum":5,"description":"Number of keys."},"tires_condition":{"type":"object","required":["value","label"],"description":"Tire condition.","properties":{"value":{"type":["string","null"],"enum":["new","good","fair","needs_replacement",null],"description":"`new` = New, `good` = Good, `fair` = Fair, `needs_replacement` = Needs replacement"},"label":{"type":["string","null"]}}},"known_issues":{"type":["array","null"],"items":{"type":"object","required":["value","label"],"properties":{"value":{"type":"string","enum":["engine","transmission","air_conditioning","electrical","oil_leak","rust","accident_repair","suspension"],"description":"`engine` = Engine, `transmission` = Transmission, `air_conditioning` = A/C, `electrical` = Electrical, `oil_leak` = Oil leak, `rust` = Body rust, `accident_repair` = Accident repair, `suspension` = Suspension"},"label":{"type":"string"}}},"description":"Known issues. `null` = not provided; `[]` = the seller states there are no known issues."}}},"ConditionInput":{"type":"object","additionalProperties":false,"description":"Condition checklist. Each item may be omitted or `null` (= not provided). Unknown keys are rejected with 400 `validation_failed` — there is no free-text field; put details in `description`.","properties":{"service_records":{"type":["boolean","null"]},"one_owner":{"type":["boolean","null"]},"smoker":{"type":["boolean","null"]},"keys_count":{"type":["integer","null"],"minimum":0,"maximum":5},"tires_condition":{"type":["string","null"],"enum":["new","good","fair","needs_replacement",null],"description":"`new` = New, `good` = Good, `fair` = Fair, `needs_replacement` = Needs replacement"},"known_issues":{"type":["array","null"],"maxItems":8,"items":{"type":"string","enum":["engine","transmission","air_conditioning","electrical","oil_leak","rust","accident_repair","suspension"]},"description":"`engine` = Engine, `transmission` = Transmission, `air_conditioning` = A/C, `electrical` = Electrical, `oil_leak` = Oil leak, `rust` = Body rust, `accident_repair` = Accident repair, `suspension` = Suspension. `[]` = no known issues; duplicates are ignored."}}},"Dealer":{"type":"object","required":["id","owner_id","name","address","zipcode","lat","lng","phone","wechat","contact_apps","store_photos","languages","created_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Store id."},"owner_id":{"type":"string","format":"uuid","description":"Profile that owns the store; use as `seller_id` on `/cars`."},"name":{"type":"string"},"address":{"type":"string"},"zipcode":{"type":["string","null"]},"lat":{"type":["number","null"]},"lng":{"type":["number","null"]},"phone":{"type":["string","null"],"description":"`null` for anonymous requests."},"wechat":{"type":["string","null"],"description":"`null` for anonymous requests."},"contact_apps":{"oneOf":[{"$ref":"#/components/schemas/ContactApps"},{"type":"null"}],"description":"Messenger accounts of the store owner. `null` for anonymous requests."},"store_photos":{"type":"array","items":{"type":"string","format":"uri"}},"languages":{"type":"array","items":{"type":"string"}},"active_count":{"type":"integer","description":"Active listings of the owner."},"created_at":{"type":"string","format":"date-time"}}},"ListingInput":{"type":"object","description":"Body of `PUT /inventory/{external_id}` (external_id comes from the path) and of each `batch` item (external_id required in the object).","required":["vin","year","make","model","price","mileage","fuel_type","transmission"],"properties":{"external_id":{"type":"string","minLength":1,"maxLength":64,"description":"Your stock number. Batch items only; on PUT it is the path segment."},"vin":{"type":"string","minLength":17,"maxLength":17,"description":"17-char VIN. Duplicate VIN under the same account returns 409 `conflict`."},"year":{"type":"integer","minimum":1980},"make":{"type":"string","maxLength":40,"description":"English make; common aliases are canonicalised (e.g. `Mercedes` → `Mercedes-Benz`)."},"model":{"type":"string","maxLength":60},"trim":{"type":["string","null"],"maxLength":60},"price":{"type":"integer","minimum":0,"description":"Whole units of `currency` (USD unless you send another supported `currency`, e.g. `\"CAD\"` / `\"AUD\"`). `0` = call for price."},"original_price":{"type":["integer","null"],"minimum":0,"description":"Same currency as `price`."},"currency":{"type":["string","null"],"enum":["USD","CAD","AUD","NZD",null],"description":"Currency of `price` / `original_price`. Omit to keep the stored value (new listings default to `USD`); `null` resets to `USD`."},"mileage":{"type":"integer","minimum":0,"description":"Odometer reading in `mileage_unit` (miles unless you send `mileage_unit: \"km\"`)."},"mileage_unit":{"type":["string","null"],"enum":["mi","km",null],"description":"Unit of `mileage`. Omit to keep the stored value (new listings default to `mi`); `null` resets to `mi`."},"fuel_type":{"type":"string","enum":["gasoline","diesel","electric","hybrid","phev","hydrogen"],"description":"`gasoline` = Gas, `diesel` = Diesel, `electric` = Electric, `hybrid` = Hybrid, `phev` = Plug-in hybrid, `hydrogen` = Hydrogen fuel cell"},"transmission":{"type":"string","enum":["automatic","manual","cvt","dct","amt","single_speed"],"description":"`automatic` = Automatic (AT), `manual` = Manual (MT), `cvt` = CVT, `dct` = DCT (Dual-Clutch), `amt` = AMT (Automated Manual), `single_speed` = Single-Speed (EV)"},"drivetrain":{"type":["string","null"],"enum":["fwd","rwd","awd","4wd",null],"description":"`fwd` = FWD, `rwd` = RWD, `awd` = AWD, `4wd` = 4WD"},"title_status":{"type":["string","null"],"enum":["clean","rebuilt","salvage","lemon_buyback","ppsr_clear","written_off",null],"description":"Title brand: `clean` = Clean title, `rebuilt` = Rebuilt title, `salvage` = Salvage title, `lemon_buyback` = Lemon buyback, `ppsr_clear` = No money owing (PPSR checked), `written_off` = Written-off. `ppsr_clear` / `written_off` are the Australian / New Zealand options (official PPSR check: no money owing / recorded insurance write-off); the US / CA brands are the others. Omit to keep the stored value (new listings start empty); send `null` to clear it."},"condition":{"oneOf":[{"$ref":"#/components/schemas/ConditionInput"},{"type":"null"}],"description":"Condition checklist. Omit to keep the stored checklist (new listings start empty); `null` clears it; an object replaces the whole checklist (items you leave out become not provided)."},"exterior_color":{"type":["string","null"],"maxLength":30,"description":"Free text in English, e.g. `white`."},"interior_color":{"type":["string","null"],"maxLength":30},"description":{"type":["string","null"],"maxLength":5000,"description":"Your own text, in any language. Stored verbatim as the original and machine-translated into the other site languages in the background."},"description_lang":{"type":["string","null"],"enum":["zh","en","ko","ja","es","fr",null],"deprecated":true,"description":"Deprecated and ignored: the language of `description` is detected automatically. Still accepted so existing integrations keep working."},"features":{"type":"array","maxItems":40,"items":{"type":"string","maxLength":40},"default":[],"description":"Feature tags in any language, stored as sent. Readers see recognized features in their own language."},"images":{"type":"array","maxItems":30,"items":{"type":"string","format":"uri"},"default":[],"description":"https URLs, max 30, each <= 10 MB. Mirrored and compressed asynchronously."},"carfax_url":{"type":["string","null"],"format":"uri"},"store_id":{"type":["string","null"],"format":"uuid","description":"Verified store to attach to. Defaults to the first verified store."},"location":{"type":["string","null"],"maxLength":80,"description":"`City, ST`, a 5-digit US ZIP, a Canadian postal code or a 4-digit Australian / New Zealand postcode (send `country` with it — both use 4 digits). Required for personal accounts; dealers default to the store address."},"country":{"type":["string","null"],"enum":["US","CA","AU","NZ",null],"description":"Country of the car (case-insensitive). Optional, except with a 4-digit postcode in `location` (`AU` or `NZ`); must match the postcode format when both are sent. Steers geocoding, and on a new listing it picks the default `currency` / `mileage_unit` when you omit them (`US` → USD / mi, `CA` → CAD / km, `AU` → AUD / km, `NZ` → NZD / km). Not stored as such: responses carry a derived `country`."}}},"InventoryItem":{"type":"object","required":["id","external_id","url","status","title","year","make","model","price","currency","mileage","mileage_unit","images","location","country","created_at","updated_at","processing_state"],"properties":{"id":{"type":"string","format":"uuid"},"external_id":{"type":["string","null"]},"url":{"type":"string","format":"uri"},"status":{"type":["string","null"],"enum":["active","pending","sold","removed",null]},"title":{"type":"string"},"year":{"type":"integer"},"make":{"type":"string"},"model":{"type":"string"},"trim":{"type":["string","null"]},"price":{"type":"integer","description":"Whole units of `currency`."},"currency":{"type":"string","enum":["USD","CAD","AUD","NZD"]},"mileage":{"type":"integer","description":"In `mileage_unit`."},"mileage_unit":{"type":"string","enum":["mi","km"]},"vin":{"type":["string","null"]},"images":{"type":"array","items":{"type":"string","format":"uri"}},"image_url":{"type":["string","null"],"format":"uri"},"fuel_type":{"$ref":"#/components/schemas/EnumValue"},"transmission":{"$ref":"#/components/schemas/EnumValue"},"drivetrain":{"$ref":"#/components/schemas/EnumValue"},"location":{"type":"string"},"country":{"type":"string","enum":["US","CA","AU","NZ"],"description":"Country of the car: `US`, `CA`, `AU` or `NZ`. Derived, not stored: inferred from the coordinates, then the location text (country / state names), then the postcode format; `US` when nothing tells."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","description":"Last change to the listing's visible content (same clock as `CarSummary.updated_at`)."},"expires_at":{"type":["string","null"],"format":"date-time"},"processing_state":{"type":"array","items":{"type":"string","enum":["images_pending","translation_pending"]},"description":"Background steps not finished yet. `images_pending`: some photos are still being copied to our storage. `translation_pending`: the Chinese or English translation of the description is not ready yet (only reported for active listings). Empty = ready."}}},"UpsertResult":{"type":"object","required":["id","external_id","url","status","created","processing","quota"],"properties":{"id":{"type":"string","format":"uuid"},"external_id":{"type":"string"},"url":{"type":"string","format":"uri"},"status":{"type":"string","enum":["active","pending","sold","removed"]},"created":{"type":"boolean","description":"`true` when this call inserted a new listing (HTTP 201)."},"processing":{"type":"array","items":{"type":"string"},"description":"Steps still running in the background: `vin` (new listing or changed VIN), `moderation` (new listing, or a change to any of description, features, year, make, model, trim), `translation` (a new or changed, non-empty description), `images` (photos still to be copied)."},"quota":{"$ref":"#/components/schemas/Quota"}}},"RemoveResult":{"type":"object","required":["id","external_id","status","quota"],"properties":{"id":{"type":"string","format":"uuid"},"external_id":{"type":"string"},"status":{"type":"string","enum":["sold","removed"]},"quota":{"$ref":"#/components/schemas/Quota"}}},"BatchResult":{"type":"object","required":["results","summary","quota"],"properties":{"results":{"type":"array","description":"Same order as `items`.","items":{"type":"object","required":["external_id","ok","status_code"],"properties":{"external_id":{"type":["string","null"]},"ok":{"type":"boolean"},"status_code":{"type":"integer","description":"HTTP status this item would have received on its own (201 created, 200 updated, 4xx error)."},"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"created":{"type":"boolean"},"processing":{"type":"array","items":{"type":"string"}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["bad_request","validation_failed","unauthorized","key_revoked","key_expired","ip_not_allowed","insufficient_scope","forbidden","account_banned","not_found","conflict","listing_blocked","rate_limited","quota_exceeded","internal_error"]},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"issue":{"type":"string"}}}},"existing_id":{"type":"string","format":"uuid"}}}}}},"summary":{"type":"object","required":["created","updated","failed"],"properties":{"created":{"type":"integer"},"updated":{"type":"integer"},"failed":{"type":"integer"}}},"quota":{"$ref":"#/components/schemas/Quota"}}},"ReconcileRef":{"type":"object","required":["id","external_id"],"properties":{"id":{"type":"string","format":"uuid"},"external_id":{"type":"string"}}},"ReconcileResult":{"oneOf":[{"type":"object","title":"Dry run","required":["dry_run","would_remove","quota"],"properties":{"dry_run":{"type":"boolean","const":true},"would_remove":{"type":"array","items":{"$ref":"#/components/schemas/ReconcileRef"}},"quota":{"$ref":"#/components/schemas/Quota"}}},{"type":"object","title":"Applied","required":["dry_run","removed","failed","quota"],"properties":{"dry_run":{"type":"boolean","const":false},"removed":{"type":"array","items":{"$ref":"#/components/schemas/ReconcileRef"},"description":"Listings marked `removed` by this call."},"failed":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/ReconcileRef"},{"type":"object","properties":{"error":{"type":"string","description":"e.g. `quota_exceeded`"}}}]},"description":"Listings that should have been removed but were not (quota ran out mid-way). Re-run later."},"quota":{"$ref":"#/components/schemas/Quota"}}}]},"Key":{"type":"object","required":["id","name","prefix","scopes","rate_limit_per_min"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"prefix":{"type":"string","description":"First 12 characters of the key, e.g. `clc_live_9Xk`."},"scopes":{"type":"array","items":{"type":"string","enum":["read:cars","read:dealers","write:inventory","write:images"]}},"rate_limit_per_min":{"type":"integer"}}},"Me":{"type":"object","required":["key","owner","tier","stores","quota"],"properties":{"key":{"$ref":"#/components/schemas/Key"},"owner":{"type":"object","required":["id","username","account_type","languages"],"properties":{"id":{"type":"string","format":"uuid"},"username":{"type":"string"},"account_type":{"type":"string","enum":["private","dealer"]},"languages":{"type":"array","items":{"type":"string"}}}},"tier":{"type":"string","enum":["personal","dealer"]},"stores":{"type":"array","description":"Verified stores of the owner (oldest first). Empty for personal tier.","items":{"type":"object","required":["id","name","address","lat","lng"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"address":{"type":"string"},"lat":{"type":["number","null"]},"lng":{"type":["number","null"]}}}},"quota":{"$ref":"#/components/schemas/Quota"}}},"MakeAgg":{"type":"object","required":["make","count","models"],"properties":{"make":{"type":"string"},"count":{"type":"integer","description":"Active listings of this make."},"models":{"type":"array","items":{"type":"object","required":["model","count"],"properties":{"model":{"type":"string"},"count":{"type":"integer"}}}}}}}},"paths":{"/cars":{"get":{"tags":["Cars"],"summary":"List active listings","description":"Cursor-paginated (`sort=newest` uses a stable keyset cursor; other sorts use an offset cursor). Anonymous requests are limited to 20/min per IP and get masked contact fields; send a key with `read:cars` for the key's own limit (default 60/min). A cursor is only valid for the sort it was issued with.","security":[{},{"ApiKey":[]}],"parameters":[{"name":"make","in":"query","required":false,"schema":{"type":"string"},"description":"Exact make (English), e.g. `Toyota`."},{"name":"model","in":"query","required":false,"schema":{"type":"string"},"description":"Exact model, e.g. `Camry`."},{"name":"year_min","in":"query","required":false,"schema":{"type":"integer"},"description":""},{"name":"year_max","in":"query","required":false,"schema":{"type":"integer"},"description":""},{"name":"price_min","in":"query","required":false,"schema":{"type":"integer"},"description":"USD. Listings in other currencies are compared after converting at fixed approximate rates (1 USD ≈ 1.38 CAD, 1.52 AUD, 1.7 NZD)."},{"name":"price_max","in":"query","required":false,"schema":{"type":"integer"},"description":"USD (other currencies converted, as for `price_min`)."},{"name":"mileage_max","in":"query","required":false,"schema":{"type":"integer"},"description":"Miles. Listings in km are compared after converting (1 mi = 1.609344 km)."},{"name":"fuel_type","in":"query","required":false,"schema":{"type":"string","enum":["gasoline","diesel","electric","hybrid","phev","hydrogen"]},"description":""},{"name":"transmission","in":"query","required":false,"schema":{"type":"string","enum":["automatic","manual","cvt","dct","amt","single_speed"]},"description":""},{"name":"drivetrain","in":"query","required":false,"schema":{"type":"string","enum":["fwd","rwd","awd","4wd"]},"description":""},{"name":"location","in":"query","required":false,"schema":{"type":"string"},"description":"Substring match on city/state, e.g. `Los Angeles` or `CA`."},{"name":"seller_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Only this seller's listings (a `Seller.id` or `Dealer.owner_id`)."},{"name":"updated_since","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Only listings whose visible content changed at or after this instant (description, features, year, make, model, trim, price, original_price, mileage, photos, status and visibility, colors, fuel type, transmission, drivetrain, location and coordinates, carfax_url, carfax_summary, VIN, source_url, seller phone); view counts and translation updates don't count. Use for incremental sync, comparing against `updated_at`."},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["newest","price_asc","price_desc","mileage_asc","year_desc"],"default":"newest"},"description":"`price_*` / `mileage_asc` order by the stored number in each listing's own `currency` / `mileage_unit` (no conversion)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":""},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from `next_cursor` of the previous page."},{"name":"lang","in":"query","required":false,"schema":{"type":"string","enum":["zh","en","ko","ja","es","fr"],"default":"zh"},"description":"Language for `title`, `location.name` and every `label`. Falls back to `Accept-Language`."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","next_cursor","lang"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CarSummary"}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page. `null` on the last page."},"lang":{"type":"string","enum":["zh","en","ko","ja","es","fr"]}}}}}},"400":{"description":"Malformed request (`bad_request`) or schema violation (`validation_failed`, see `details`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key (`unauthorized`), or key revoked / expired (`key_revoked`, `key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the scope (`insufficient_scope`), IP not allowed (`ip_not_allowed`) or account banned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-minute rate limit (`rate_limited`, see `Retry-After`) or daily write quota (`quota_exceeded`, body includes `quota`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cars/{id}":{"get":{"tags":["Cars"],"summary":"Get one listing","description":"`description` and `features` are in the requested `lang` once their translation is ready; `description_original` / `features_original` always carry the seller's own text.","security":[{},{"ApiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Listing UUID"},{"name":"lang","in":"query","required":false,"schema":{"type":"string","enum":["zh","en","ko","ja","es","fr"],"default":"zh"},"description":"Language for `title`, `location.name` and every `label`. Falls back to `Accept-Language`."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","lang"],"properties":{"data":{"$ref":"#/components/schemas/CarDetail"},"lang":{"type":"string","enum":["zh","en","ko","ja","es","fr"]}}}}}},"400":{"description":"Malformed request (`bad_request`) or schema violation (`validation_failed`, see `details`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key (`unauthorized`), or key revoked / expired (`key_revoked`, `key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the scope (`insufficient_scope`), IP not allowed (`ip_not_allowed`) or account banned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found or not public.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-minute rate limit (`rate_limited`, see `Retry-After`) or daily write quota (`quota_exceeded`, body includes `quota`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/dealers":{"get":{"tags":["Dealers"],"summary":"List verified dealer stores","security":[{},{"ApiKey":[]}],"parameters":[{"name":"location","in":"query","required":false,"schema":{"type":"string"},"description":"Substring match on the store address."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":""},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from `next_cursor` of the previous page."},{"name":"lang","in":"query","required":false,"schema":{"type":"string","enum":["zh","en","ko","ja","es","fr"],"default":"zh"},"description":"Language for `title`, `location.name` and every `label`. Falls back to `Accept-Language`."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","next_cursor","lang"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Dealer"}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page. `null` on the last page."},"lang":{"type":"string","enum":["zh","en","ko","ja","es","fr"]}}}}}},"400":{"description":"Malformed request (`bad_request`) or schema violation (`validation_failed`, see `details`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key (`unauthorized`), or key revoked / expired (`key_revoked`, `key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the scope (`insufficient_scope`), IP not allowed (`ip_not_allowed`) or account banned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-minute rate limit (`rate_limited`, see `Retry-After`) or daily write quota (`quota_exceeded`, body includes `quota`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/dealers/{id}":{"get":{"tags":["Dealers"],"summary":"Get a store with its active listings","security":[{},{"ApiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Store UUID"},{"name":"lang","in":"query","required":false,"schema":{"type":"string","enum":["zh","en","ko","ja","es","fr"],"default":"zh"},"description":"Language for `title`, `location.name` and every `label`. Falls back to `Accept-Language`."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","lang"],"properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Dealer"},{"type":"object","required":["cars"],"properties":{"cars":{"type":"array","items":{"$ref":"#/components/schemas/CarSummary"}}}}]},"lang":{"type":"string","enum":["zh","en","ko","ja","es","fr"]}}}}}},"400":{"description":"Malformed request (`bad_request`) or schema violation (`validation_failed`, see `details`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key (`unauthorized`), or key revoked / expired (`key_revoked`, `key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the scope (`insufficient_scope`), IP not allowed (`ip_not_allowed`) or account banned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found or not verified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-minute rate limit (`rate_limited`, see `Retry-After`) or daily write quota (`quota_exceeded`, body includes `quota`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/meta/makes":{"get":{"tags":["Meta"],"summary":"Makes and models with active counts, plus the enum catalog","description":"Same aggregation the browse filters use. Cached for 5 minutes. `enums` lists every accepted slug with its label in `lang`.","security":[{},{"ApiKey":[]}],"parameters":[{"name":"lang","in":"query","required":false,"schema":{"type":"string","enum":["zh","en","ko","ja","es","fr"],"default":"zh"},"description":"Language for `title`, `location.name` and every `label`. Falls back to `Accept-Language`."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","enums","lang"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MakeAgg"}},"enums":{"type":"object","properties":{"fuel_type":{"type":"array","items":{"type":"object","required":["value","label"],"properties":{"value":{"type":"string"},"label":{"type":"string"}}}},"transmission":{"type":"array","items":{"type":"object","required":["value","label"],"properties":{"value":{"type":"string"},"label":{"type":"string"}}}},"drivetrain":{"type":"array","items":{"type":"object","required":["value","label"],"properties":{"value":{"type":"string"},"label":{"type":"string"}}}},"title_status":{"type":"array","items":{"type":"object","required":["value","label"],"properties":{"value":{"type":"string"},"label":{"type":"string"}}}},"tires_condition":{"type":"array","items":{"type":"object","required":["value","label"],"properties":{"value":{"type":"string"},"label":{"type":"string"}}}},"known_issue":{"type":"array","items":{"type":"object","required":["value","label"],"properties":{"value":{"type":"string"},"label":{"type":"string"}}}},"status":{"type":"array","items":{"type":"object","required":["value","label"],"properties":{"value":{"type":"string"},"label":{"type":"string"}}}}}},"lang":{"type":"string","enum":["zh","en","ko","ja","es","fr"]}}}}}},"400":{"description":"Malformed request (`bad_request`) or schema violation (`validation_failed`, see `details`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key (`unauthorized`), or key revoked / expired (`key_revoked`, `key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the scope (`insufficient_scope`), IP not allowed (`ip_not_allowed`) or account banned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-minute rate limit (`rate_limited`, see `Retry-After`) or daily write quota (`quota_exceeded`, body includes `quota`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me":{"get":{"tags":["Inventory"],"summary":"Current key, owner, stores and quota","description":"Any scope. Use it to verify a key and to read the quota before a sync run.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"400":{"description":"Malformed request (`bad_request`) or schema violation (`validation_failed`, see `details`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key (`unauthorized`), or key revoked / expired (`key_revoked`, `key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the scope (`insufficient_scope`), IP not allowed (`ip_not_allowed`) or account banned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-minute rate limit (`rate_limited`, see `Retry-After`) or daily write quota (`quota_exceeded`, body includes `quota`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/inventory":{"get":{"tags":["Inventory"],"summary":"List my API-managed listings","description":"Every listing of the key owner, including `pending` / `sold` / `removed` and manually posted ones (no `external_id`, adoptable via `?adopt=true`). Most recently changed first. Requires `write:inventory`.","security":[{"ApiKey":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["active","pending","sold","removed"]},"description":""},{"name":"external_id","in":"query","required":false,"schema":{"type":"string"},"description":"Exact match."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":""},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from `next_cursor` of the previous page."},{"name":"lang","in":"query","required":false,"schema":{"type":"string","enum":["zh","en","ko","ja","es","fr"],"default":"zh"},"description":"Language for `title`, `location.name` and every `label`. Falls back to `Accept-Language`."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","next_cursor","lang"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InventoryItem"}},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page. `null` on the last page."},"lang":{"type":"string","enum":["zh","en","ko","ja","es","fr"]}}}}}},"400":{"description":"Malformed request (`bad_request`) or schema violation (`validation_failed`, see `details`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key (`unauthorized`), or key revoked / expired (`key_revoked`, `key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the scope (`insufficient_scope`), IP not allowed (`ip_not_allowed`) or account banned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-minute rate limit (`rate_limited`, see `Retry-After`) or daily write quota (`quota_exceeded`, body includes `quota`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/inventory/{external_id}":{"parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"Your stock number (1–64 chars). Unique per account; URL-encode it."}],"get":{"tags":["Inventory"],"summary":"Get one of my listings by external_id","security":[{"ApiKey":[]}],"parameters":[{"name":"lang","in":"query","required":false,"schema":{"type":"string","enum":["zh","en","ko","ja","es","fr"],"default":"zh"},"description":"Language for `title`, `location.name` and every `label`. Falls back to `Accept-Language`."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","lang"],"properties":{"data":{"$ref":"#/components/schemas/InventoryItem"},"lang":{"type":"string","enum":["zh","en","ko","ja","es","fr"]}}}}}},"400":{"description":"Malformed request (`bad_request`) or schema violation (`validation_failed`, see `details`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key (`unauthorized`), or key revoked / expired (`key_revoked`, `key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the scope (`insufficient_scope`), IP not allowed (`ip_not_allowed`) or account banned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No listing with this external_id under this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-minute rate limit (`rate_limited`, see `Retry-After`) or daily write quota (`quota_exceeded`, body includes `quota`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Inventory"],"summary":"Create or update a listing (idempotent upsert)","description":"The core write endpoint. First PUT for an external_id inserts (counts as an *insert*, HTTP 201); later PUTs update (count as an *update*, HTTP 200), and re-activate a `sold`/`removed` listing — except one removed by moderation or an administrator (409 `listing_blocked`). Returns as soon as the row is written; VIN check, image mirroring, AI moderation and translation run in the background (see `processing`). Every new listing is moderated; a later PUT is moderated again only when any of description, features, year, make, model, trim changed, and translated again only when the description changed. Requires `write:inventory`.","security":[{"ApiKey":[]}],"parameters":[{"name":"adopt","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"When a manually posted listing with the same VIN exists under this account (409 `conflict` with `existing_id`), pass `true` to attach this external_id to it instead of creating a duplicate."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingInput"}}}},"responses":{"200":{"description":"Updated","headers":{"X-Quota-Tier":{"schema":{"type":"string","enum":["personal","dealer"]},"description":"Quota tier of the key owner."},"X-Quota-Inserts-Remaining":{"schema":{"type":"integer"},"description":"New listings still allowed today (UTC)."},"X-Quota-Updates-Remaining":{"schema":{"type":"integer"},"description":"Updates still allowed today (UTC)."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertResult"}}}},"201":{"description":"Created","headers":{"X-Quota-Tier":{"schema":{"type":"string","enum":["personal","dealer"]},"description":"Quota tier of the key owner."},"X-Quota-Inserts-Remaining":{"schema":{"type":"integer"},"description":"New listings still allowed today (UTC)."},"X-Quota-Updates-Remaining":{"schema":{"type":"integer"},"description":"Updates still allowed today (UTC)."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertResult"}}}},"400":{"description":"Malformed request (`bad_request`) or schema violation (`validation_failed`, see `details`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key (`unauthorized`), or key revoked / expired (`key_revoked`, `key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the scope (`insufficient_scope`), IP not allowed (`ip_not_allowed`) or account banned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`: same VIN already exists under this account (see `existing_id`). `listing_blocked`: the listing was removed by moderation or an administrator and can't be relisted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-minute rate limit (`rate_limited`, see `Retry-After`) or daily write quota (`quota_exceeded`, body includes `quota`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Inventory"],"summary":"Mark a listing sold or removed","description":"Counts as an *update*. `removed` also drops our mirrored copies of the images. Requires `write:inventory`.","security":[{"ApiKey":[]}],"parameters":[{"name":"reason","in":"query","required":false,"schema":{"type":"string","enum":["sold","removed"],"default":"sold"},"description":""}],"responses":{"200":{"description":"OK","headers":{"X-Quota-Tier":{"schema":{"type":"string","enum":["personal","dealer"]},"description":"Quota tier of the key owner."},"X-Quota-Inserts-Remaining":{"schema":{"type":"integer"},"description":"New listings still allowed today (UTC)."},"X-Quota-Updates-Remaining":{"schema":{"type":"integer"},"description":"Updates still allowed today (UTC)."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoveResult"}}}},"400":{"description":"Malformed request (`bad_request`) or schema violation (`validation_failed`, see `details`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key (`unauthorized`), or key revoked / expired (`key_revoked`, `key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the scope (`insufficient_scope`), IP not allowed (`ip_not_allowed`) or account banned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No listing with this external_id under this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-minute rate limit (`rate_limited`, see `Retry-After`) or daily write quota (`quota_exceeded`, body includes `quota`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/inventory/{external_id}/images":{"post":{"tags":["Inventory"],"summary":"Replace the image list of a listing","description":"Same rules as `ListingInput.images`. Mirroring happens in the background. Counts as an *update*. Requires `write:images`.","security":[{"ApiKey":[]}],"parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"Your stock number."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["images"],"properties":{"images":{"type":"array","maxItems":30,"items":{"type":"string","format":"uri"}}}}}}},"responses":{"200":{"description":"OK","headers":{"X-Quota-Tier":{"schema":{"type":"string","enum":["personal","dealer"]},"description":"Quota tier of the key owner."},"X-Quota-Inserts-Remaining":{"schema":{"type":"integer"},"description":"New listings still allowed today (UTC)."},"X-Quota-Updates-Remaining":{"schema":{"type":"integer"},"description":"Updates still allowed today (UTC)."}},"content":{"application/json":{"schema":{"type":"object","required":["id","external_id","images","processing","quota"],"properties":{"id":{"type":"string","format":"uuid"},"external_id":{"type":"string"},"images":{"type":"array","items":{"type":"string","format":"uri"}},"processing":{"type":"array","items":{"type":"string"},"description":"`[\"images\"]` while mirroring runs."},"quota":{"$ref":"#/components/schemas/Quota"}}}}}},"400":{"description":"Malformed request (`bad_request`) or schema violation (`validation_failed`, see `details`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key (`unauthorized`), or key revoked / expired (`key_revoked`, `key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the scope (`insufficient_scope`), IP not allowed (`ip_not_allowed`) or account banned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No listing with this external_id under this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-minute rate limit (`rate_limited`, see `Retry-After`) or daily write quota (`quota_exceeded`, body includes `quota`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/inventory/batch":{"post":{"tags":["Inventory"],"summary":"Upsert up to 100 listings in one call","description":"Each item is validated and written independently; quota is charged per item. Items after the quota is exhausted come back with `quota_exceeded` while earlier ones stay written. The call itself returns 200 unless every item failed (then 400). Requires `write:inventory`.","security":[{"ApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":100,"items":{"allOf":[{"$ref":"#/components/schemas/ListingInput"},{"type":"object","required":["external_id"]}]}}}}}}},"responses":{"200":{"description":"Per-item results","headers":{"X-Quota-Tier":{"schema":{"type":"string","enum":["personal","dealer"]},"description":"Quota tier of the key owner."},"X-Quota-Inserts-Remaining":{"schema":{"type":"integer"},"description":"New listings still allowed today (UTC)."},"X-Quota-Updates-Remaining":{"schema":{"type":"integer"},"description":"Updates still allowed today (UTC)."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResult"}}}},"400":{"description":"Malformed request (`bad_request`) or schema violation (`validation_failed`, see `details`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key (`unauthorized`), or key revoked / expired (`key_revoked`, `key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the scope (`insufficient_scope`), IP not allowed (`ip_not_allowed`) or account banned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-minute rate limit (`rate_limited`, see `Retry-After`) or daily write quota (`quota_exceeded`, body includes `quota`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/inventory/reconcile":{"post":{"tags":["Inventory"],"summary":"Full reconcile: remove everything not in the list","description":"Send the complete set of external_ids currently in stock. Active listings with an external_id missing from the list are marked `removed` (each counts as an *update*; on quota exhaustion the rest are reported in `failed`). An empty list is rejected to prevent wiping the inventory by accident. Use `dry_run` to preview. Requires `write:inventory`.","security":[{"ApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["active_external_ids"],"properties":{"active_external_ids":{"type":"array","minItems":1,"items":{"type":"string"}},"dry_run":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"OK","headers":{"X-Quota-Tier":{"schema":{"type":"string","enum":["personal","dealer"]},"description":"Quota tier of the key owner."},"X-Quota-Inserts-Remaining":{"schema":{"type":"integer"},"description":"New listings still allowed today (UTC)."},"X-Quota-Updates-Remaining":{"schema":{"type":"integer"},"description":"Updates still allowed today (UTC)."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReconcileResult"}}}},"400":{"description":"Malformed request (`bad_request`) or schema violation (`validation_failed`, see `details`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key (`unauthorized`), or key revoked / expired (`key_revoked`, `key_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the scope (`insufficient_scope`), IP not allowed (`ip_not_allowed`) or account banned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-minute rate limit (`rate_limited`, see `Retry-After`) or daily write quota (`quota_exceeded`, body includes `quota`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/openapi.json":{"get":{"tags":["Meta"],"summary":"This document","security":[{}],"responses":{"200":{"description":"OpenAPI 3.1 JSON"}}}}}}