{"openapi":"3.1.0","info":{"title":"CarStack Partner API","version":"1.0.0","description":"Read-only access to JP auction vehicle data, with image delivery branded for the authenticated partner.","contact":{"url":"https://carstack.dev/docs"}},"servers":[{"url":"https://carstack.dev/v1"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Vehicles","description":"Search and retrieve auction vehicle metadata."},{"name":"Images","description":"Stream partner-branded images."},{"name":"Reference","description":"Discover the values accepted by vehicle filters."}],"paths":{"/vehicles":{"get":{"operationId":"listVehicles","tags":["Vehicles"],"summary":"List and search vehicles","parameters":[{"name":"q","in":"query","required":false,"description":"Substring search across make, model, and title.","schema":{"type":"string"}},{"name":"make","in":"query","required":false,"description":"Vehicle make. Case, spacing, and punctuation insensitive, and matched on whole words, so `toyota` also returns `AMERICA TOYOTA`. Repeat to OR several makes. See `/makes`.","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"model","in":"query","required":false,"description":"Vehicle model, matched like `make`. Repeat to OR several models. See `/makes`.","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"year_min","in":"query","required":false,"description":"Minimum model year.","schema":{"type":"integer"}},{"name":"year_max","in":"query","required":false,"description":"Maximum model year.","schema":{"type":"integer"}},{"name":"price_min","in":"query","required":false,"description":"Minimum current price in JPY.","schema":{"type":"integer","minimum":0}},{"name":"price_max","in":"query","required":false,"description":"Maximum current price in JPY.","schema":{"type":"integer","minimum":0}},{"name":"odometer_min","in":"query","required":false,"description":"Minimum odometer in kilometers.","schema":{"type":"integer","minimum":0}},{"name":"odometer_max","in":"query","required":false,"description":"Maximum odometer in kilometers.","schema":{"type":"integer","minimum":0}},{"name":"transmissions","in":"query","required":false,"description":"Transmission values.","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","enum":["automatic","manual","cvt","unknown"]}}},{"name":"steering","in":"query","required":false,"description":"Steering position.","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","enum":["lhd","rhd"]}}},{"name":"colors","in":"query","required":false,"description":"Exterior color values.","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"auction_grades","in":"query","required":false,"description":"Auction grade values.","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"auction_houses","in":"query","required":false,"description":"Auction house names.","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"sort","in":"query","required":false,"description":"Result ordering.","schema":{"type":"string","enum":["ending_soon","price_asc","price_desc","year_asc","year_desc","mileage_asc","mileage_desc"],"default":"ending_soon"}},{"name":"page","in":"query","required":false,"description":"Page number.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Results per page.","schema":{"type":"integer","minimum":1,"maximum":50,"default":24}}],"responses":{"200":{"description":"Paginated vehicle summaries.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/VehicleSummary"}},"meta":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"Missing or invalid API token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The partner does not have access to this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The resource was not found or is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The service is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/vehicles/{vehicle_id}":{"get":{"operationId":"getVehicle","tags":["Vehicles"],"summary":"Retrieve vehicle metadata","parameters":[{"name":"vehicle_id","in":"path","required":true,"description":"Stable public vehicle identifier.","schema":{"type":"string"}}],"responses":{"200":{"description":"Vehicle detail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Vehicle"}}}},"401":{"description":"Missing or invalid API token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The partner does not have access to this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The resource was not found or is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The service is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/makes":{"get":{"operationId":"listMakes","tags":["Reference"],"summary":"List makes and models","description":"Every make in the catalog with its models and vehicle counts. Authoritative source for the `make` and `model` query parameters.","responses":{"200":{"description":"Makes ordered by vehicle count.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Make"}},"meta":{"type":"object","required":["total_makes","total_models","vehicle_count"],"properties":{"total_makes":{"type":"integer","minimum":0},"total_models":{"type":"integer","minimum":0},"vehicle_count":{"type":"integer","minimum":0}}}}}}}},"401":{"description":"Missing or invalid API token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The partner does not have access to this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The resource was not found or is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The service is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/filters":{"get":{"operationId":"listFilters","tags":["Reference"],"summary":"List filter values and ranges","description":"Every remaining enumerable filter value with counts, plus the numeric ranges present in the catalog.","responses":{"200":{"description":"Filter values and ranges.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["colors","transmissions","steering","auction_grades","auction_houses","sort","year","price_jpy","odometer_km"],"properties":{"colors":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["value","vehicle_count"],"properties":{"value":{"type":"string"},"vehicle_count":{"type":"integer","minimum":0}}}},"transmissions":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["value","vehicle_count"],"properties":{"value":{"type":"string"},"vehicle_count":{"type":"integer","minimum":0}}}},"steering":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["value","vehicle_count"],"properties":{"value":{"type":"string"},"vehicle_count":{"type":"integer","minimum":0}}}},"auction_grades":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["value","vehicle_count"],"properties":{"value":{"type":"string"},"vehicle_count":{"type":"integer","minimum":0}}}},"auction_houses":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["value","vehicle_count"],"properties":{"value":{"type":"string"},"vehicle_count":{"type":"integer","minimum":0}}}},"sort":{"type":"array","items":{"type":"string"}},"year":{"$ref":"#/components/schemas/Range"},"price_jpy":{"$ref":"#/components/schemas/Range"},"odometer_km":{"$ref":"#/components/schemas/Range"}}},"meta":{"type":"object","required":["vehicle_count"],"properties":{"vehicle_count":{"type":"integer","minimum":0}}}}}}}},"401":{"description":"Missing or invalid API token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The partner does not have access to this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The resource was not found or is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The service is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/images/{image_id}":{"get":{"operationId":"getImage","tags":["Images"],"summary":"Stream a partner-branded JPEG","description":"Streams a JPEG rendered for the partner that owns the API token. Use the `url` values returned by the vehicle endpoints rather than composing this path. EXIF `Artist` and `Copyright` carry the partner logo text, `ImageDescription` adds the contact number and `Delivered via carstack.dev`, and `Software` is `carstack.dev`.","parameters":[{"name":"image_id","in":"path","required":true,"description":"Partner-delivery image identifier.","schema":{"type":"integer"}},{"name":"If-None-Match","in":"header","required":false,"schema":{"type":"string"},"description":"Previously returned ETag for conditional retrieval."},{"name":"If-Modified-Since","in":"header","required":false,"schema":{"type":"string"},"description":"Previously returned Last-Modified value."}],"responses":{"200":{"description":"Partner-branded JPEG.","headers":{"ETag":{"schema":{"type":"string"},"description":"Image representation validator."},"Last-Modified":{"schema":{"type":"string"},"description":"Last representation update time."}},"content":{"image/jpeg":{"schema":{"type":"string","contentEncoding":"binary"}}}},"304":{"description":"The cached image is still current."},"401":{"description":"Missing or invalid API token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The partner does not have access to this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The resource was not found or is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The service is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"csk_live_…","description":"Partner API token. Keep it in a server-side secret store."}},"schemas":{"Auction":{"type":"object","additionalProperties":false,"required":["house","date","status"],"properties":{"house":{"type":["string","null"]},"date":{"type":["string","null"],"format":"date-time"},"status":{"type":["string","null"]}}},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message","status"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}}}}},"Image":{"type":"object","additionalProperties":false,"required":["id","kind","position","url","updated_at"],"properties":{"id":{"type":"integer"},"kind":{"type":"string","enum":["thumbnail","gallery","spec"]},"position":{"type":"integer"},"url":{"type":"string","format":"uri"},"updated_at":{"type":"string","format":"date-time"}}},"Make":{"type":"object","additionalProperties":false,"required":["name","vehicle_count","models"],"properties":{"name":{"type":"string"},"vehicle_count":{"type":"integer","minimum":0},"models":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["name","vehicle_count"],"properties":{"name":{"type":"string"},"vehicle_count":{"type":"integer","minimum":0}}}}}},"Range":{"type":"object","additionalProperties":false,"required":["min","max"],"properties":{"min":{"type":["integer","null"]},"max":{"type":["integer","null"]}}},"ImageSummary":{"type":"object","additionalProperties":false,"required":["total","primary_url"],"properties":{"total":{"type":"integer","minimum":0},"primary_url":{"type":["string","null"],"format":"uri"}}},"Pagination":{"type":"object","additionalProperties":false,"required":["page","per_page","total_count","total_pages"],"properties":{"page":{"type":"integer","minimum":1},"per_page":{"type":"integer","minimum":1,"maximum":50},"total_count":{"type":"integer","minimum":0},"total_pages":{"type":"integer","minimum":0}}},"Price":{"type":"object","additionalProperties":false,"required":["current","currency"],"properties":{"current":{"type":["integer","null"]},"start":{"type":["integer","null"]},"final":{"type":["integer","null"]},"currency":{"type":"string","const":"JPY"}}},"Specs":{"type":"object","additionalProperties":false,"required":["engine","engine_cc","transmission","steering","color","equipment"],"properties":{"engine":{"type":["string","null"]},"engine_cc":{"type":["integer","null"]},"transmission":{"type":["string","null"]},"steering":{"type":["string","null"]},"color":{"type":["string","null"]},"equipment":{"type":["string","null"]}}},"Vehicle":{"allOf":[{"$ref":"#/components/schemas/VehicleSummary"},{"type":"object","required":["chassis_code"],"properties":{"chassis_code":{"type":["string","null"]},"images":{"allOf":[{"$ref":"#/components/schemas/ImageSummary"},{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Image"}}}}]}}}]},"VehicleSummary":{"type":"object","additionalProperties":false,"required":["id","lot_number","title","make","model","year","grade","auction","price","odometer_km","specs","images"],"properties":{"id":{"type":"string"},"lot_number":{"type":["string","null"]},"title":{"type":["string","null"]},"make":{"type":["string","null"]},"model":{"type":["string","null"]},"year":{"type":["integer","null"]},"grade":{"type":["string","null"]},"auction":{"$ref":"#/components/schemas/Auction"},"price":{"$ref":"#/components/schemas/Price"},"odometer_km":{"type":["integer","null"]},"specs":{"$ref":"#/components/schemas/Specs"},"images":{"$ref":"#/components/schemas/ImageSummary"}}}}}}