{"openapi":"3.0.3","info":{"title":"LMN Open API","version":"1.0.0","description":"Partner-facing API for LMN inventory, orders, and fulfillment. Served at sandbox-api.lmnauto.com and api.lmnauto.com. All auth via the `x-api-key` header; sandbox keys start with `lmn_stg_`, production with `lmn_prd_`."},"servers":[{"url":"https://api.lmnauto.com","description":"Production"},{"url":"https://sandbox-api.lmnauto.com","description":"Sandbox"}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"x-api-key"}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"Client-generated UUID. Replaying the same key returns the original result without creating a new order."},"CursorParam":{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from a previous response's `next_cursor`."},"LimitParam":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Page size. Default 50, max 200."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code. Branch client logic on this, not `message`.","enum":["missing_api_key","invalid_api_key","ip_not_allowed","missing_idempotency_key","idempotency_key_reused","missing_max_bid","validation_error","vehicle_not_found","order_not_found","duplicate_order","past_order_cutoff","invalid_status_transition","invalid_cursor","rate_limited","internal_error"]},"message":{"type":"string","description":"Human-readable summary. May evolve between versions; do not branch on it."},"request_id":{"type":"string","pattern":"^req_[0-9a-f]{24}$"},"details":{"type":"object","additionalProperties":true,"description":"Optional structured context. Keys depend on the error `code`.","properties":{"issues":{"type":"array","description":"Set on `validation_error`. One entry per failing field.","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"existing_order_id":{"type":"string","description":"Set on `duplicate_order`."},"original_vehicle_id":{"type":"string","description":"Set on `idempotency_key_reused`."},"cutoff_at":{"type":"string","format":"date-time","description":"Set on `past_order_cutoff`."},"now":{"type":"string","format":"date-time"},"field":{"type":"string","description":"Set on `validation_error` when a single field triggered the error."}}}}}}},"Health":{"type":"object","required":["status","db","bq"],"properties":{"status":{"type":"string","enum":["ok","degraded"]},"db":{"type":"string","enum":["ok","fail"]},"bq":{"type":"string","enum":["ok","fail"]}}},"SourceEnum":{"type":"string","enum":["glovis","sk","aj","lotte","kcar","dealer"]},"AccidentGrade":{"type":"string","enum":["A","B","C","D","F"],"description":"Accident-history grade. Null for dealer rows."},"ExteriorGrade":{"type":"string","enum":["A","B","C","D","F"],"description":"Exterior condition letter. For Glovis/KCar, derived from the 1–9 condition score (A=8–9, B=6–7, C=4–5, D=2–3, F=1)."},"Pricing":{"type":"object","required":["listing_usd","delta_pct"],"properties":{"listing_usd":{"type":"integer","minimum":0,"description":"Estimated final price in whole USD. Converted from KRW using the daily ECB rate cached server-side."},"delta_pct":{"type":"number","nullable":true,"description":"Average sold-vs-starting delta percent from comparable auctions. Null for dealer rows."}}},"PricingDetail":{"allOf":[{"$ref":"#/components/schemas/Pricing"},{"type":"object","properties":{"breakdown_usd":{"type":"object","properties":{"auction_fee":{"type":"integer","nullable":true},"lmn_commission":{"type":"integer","nullable":true},"korean_export":{"type":"integer","nullable":true},"ocean_freight":{"type":"integer","nullable":true},"estimated_landed":{"type":"integer","nullable":true,"description":"Sum of listing_usd + all fees."}}},"history":{"type":"array","items":{"type":"object","required":["auction_date","price_usd","result"],"properties":{"auction_date":{"type":"string","format":"date"},"price_usd":{"type":"integer"},"result":{"type":"string"}}}}}}]},"VehicleSummary":{"type":"object","required":["id","source","make","model","year","mileage_km","fuel","pricing"],"properties":{"id":{"type":"string"},"source":{"$ref":"#/components/schemas/SourceEnum"},"make":{"type":"string"},"model":{"type":"string"},"trim":{"type":"string","nullable":true},"year":{"type":"integer"},"mileage_km":{"type":"integer","minimum":0},"fuel":{"type":"string","description":"Lowercase token (gasoline, diesel, hybrid, electric, lpg)."},"transmission":{"type":"string","nullable":true,"description":"Data token (A/T, M/T, CVT, DCT)."},"color":{"type":"string","nullable":true},"engine_cc":{"type":"integer","nullable":true},"drivetrain":{"type":"string","nullable":true,"enum":["FWD","RWD","AWD","4WD","2WD",null]},"options":{"type":"array","items":{"type":"string"}},"accident_grade":{"$ref":"#/components/schemas/AccidentGrade","nullable":true},"exterior_grade":{"$ref":"#/components/schemas/ExteriorGrade","nullable":true},"auction_date":{"type":"string","format":"date-time","nullable":true,"description":"KST offset ISO 8601. Null for dealer rows."},"order_cutoff_at":{"type":"string","format":"date-time","nullable":true,"description":"Orders must be placed before this timestamp (auction_date − 1 day, 00:00 KST)."},"thumbnail_url":{"type":"string","format":"uri","nullable":true},"pricing":{"$ref":"#/components/schemas/Pricing"},"sold_price_usd":{"type":"integer","nullable":true},"auction_result":{"type":"string","nullable":true,"enum":["no_bid","sold","negotiation_sold","negotiation_no_bid","past",null]},"auction_count":{"type":"integer","nullable":true}}},"VehicleDetail":{"allOf":[{"$ref":"#/components/schemas/VehicleSummary"},{"type":"object","properties":{"vin":{"type":"string","nullable":true},"license_plate":{"type":"string","nullable":true},"photos":{"type":"array","items":{"type":"string","format":"uri"}},"body_condition":{"type":"object","nullable":true,"additionalProperties":true},"inspection_report":{"type":"object","nullable":true,"additionalProperties":true},"pricing":{"$ref":"#/components/schemas/PricingDetail"}}}]},"Facets":{"type":"object","required":["makes","models","fuels","transmissions","sources","as_of"],"properties":{"makes":{"type":"array","items":{"type":"string"}},"models":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Keyed by make. e.g., {\"Toyota\":[\"Camry\",\"RAV4\"], \"Hyundai\":[...]}"},"fuels":{"type":"array","items":{"type":"string"}},"transmissions":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/SourceEnum"}},"as_of":{"type":"string","format":"date-time","nullable":true,"description":"Snapshot timestamp for the underlying inventory cache. 5-minute cache."}}},"VehicleList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/VehicleSummary"}},"next_cursor":{"type":"string","nullable":true}}},"OrderStatus":{"type":"string","enum":["proceed","cancelled","acquiring","failed","secured","shipping","delivered"]},"FulfillmentDetail":{"type":"string","nullable":true,"enum":["in_transit","in_customs","at_destination_port","delivered",null]},"Shipment":{"type":"object","nullable":true,"properties":{"vessel_name":{"type":"string","nullable":true},"container_no":{"type":"string","nullable":true},"bl_no":{"type":"string","nullable":true},"departure_port":{"type":"string","nullable":true},"arrival_port":{"type":"string","nullable":true},"etd":{"type":"string","format":"date","nullable":true},"eta":{"type":"string","format":"date","nullable":true}}},"Order":{"type":"object","required":["id","vehicle_id","status","amounts","created_at","updated_at"],"properties":{"id":{"type":"string","description":"ULID."},"vehicle_id":{"type":"string"},"status":{"$ref":"#/components/schemas/OrderStatus"},"fulfillment_detail":{"$ref":"#/components/schemas/FulfillmentDetail"},"amounts":{"type":"object","required":["purchase_price_usd","auction_fee_usd"],"properties":{"purchase_price_usd":{"type":"integer","nullable":true,"description":"Whole USD. Null until status=acquired."},"auction_fee_usd":{"type":"integer","nullable":true}}},"max_bid_amount_usd":{"type":"integer","nullable":true},"is_highest_bid":{"type":"boolean","nullable":true,"description":"True if this order carries the highest active max_bid for the vehicle at response time. Null for non-auction sources."},"current_max_bid_usd":{"type":"integer","nullable":true,"description":"Highest active max_bid across all partners for this vehicle."},"fx_rate":{"type":"number","nullable":true,"description":"KRW per USD snapshot at settlement. Null until status=acquired."},"auction_date":{"type":"string","format":"date-time","nullable":true},"order_cutoff_at":{"type":"string","format":"date-time","nullable":true},"acquired_at":{"type":"string","format":"date-time","nullable":true},"shipped_at":{"type":"string","format":"date-time","nullable":true},"shipment":{"$ref":"#/components/schemas/Shipment"},"failure_reason":{"type":"string","nullable":true,"enum":["outbid","auction_passed","seller_withdrew","payment_failed","customs_rejected",null]},"cancellation_reason":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"OrderList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"next_cursor":{"type":"string","nullable":true}}},"OrderEvent":{"type":"object","required":["id","order_id","event_type","occurred_at"],"properties":{"id":{"type":"string"},"order_id":{"type":"string"},"event_type":{"type":"string","enum":["order.created","order.status_changed","order.cancelled","order.fulfillment_updated"]},"from_status":{"$ref":"#/components/schemas/OrderStatus","nullable":true},"to_status":{"$ref":"#/components/schemas/OrderStatus","nullable":true},"actor":{"type":"string","description":"partner_id or 'lmn' for internal transitions."},"occurred_at":{"type":"string","format":"date-time"},"metadata":{"type":"object","additionalProperties":true,"nullable":true}}},"OrderEventList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OrderEvent"}}}},"CreateOrderRequest":{"type":"object","required":["vehicle_id"],"properties":{"vehicle_id":{"type":"string","minLength":1},"max_bid_amount_usd":{"type":"integer","minimum":1,"nullable":true,"description":"Required for auction sources (glovis/sk/aj/lotte/kcar). Null only for dealer."}}},"StatusUpdateRequest":{"type":"object","description":"Partner-pushed status update. Only `status: delivered` and `fulfillment_detail` transitions are partner-permitted.","properties":{"status":{"type":"string","enum":["delivered"]},"fulfillment_detail":{"$ref":"#/components/schemas/FulfillmentDetail"},"occurred_at":{"type":"string","format":"date-time"},"notes":{"type":"string"}}}},"responses":{"UnauthorizedError":{"description":"API key missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ForbiddenError":{"description":"IP not in allowlist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFoundError":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ValidationError":{"description":"Request validation failed. See details.issues for per-field errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ConflictError":{"description":"Request conflicts with current resource state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimitError":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"security":[{"ApiKey":[]}],"paths":{"/v1/health":{"get":{"operationId":"getHealth","security":[],"summary":"Health check","description":"Checks DB and BigQuery connectivity. Public — no API key required.","responses":{"200":{"description":"All systems healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}},"503":{"description":"Degraded — DB or BigQuery unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/v1/openapi.json":{"get":{"operationId":"getOpenApiSpec","security":[],"summary":"This OpenAPI spec","description":"Returns the live OpenAPI 3.1 document describing this API. Public.","responses":{"200":{"description":"OpenAPI document","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/vehicles/facets":{"get":{"operationId":"getVehicleFacets","summary":"Filter value aggregations","description":"Distinct filter values in the live catalog (last ~14 days). Intended for populating browse-UI dropdowns. Cached 5 minutes server-side; `as_of` reflects the snapshot time.","parameters":[{"name":"source","in":"query","schema":{"type":"string"},"description":"CSV of source enum values to scope the facets (e.g., `glovis,sk`)."}],"responses":{"200":{"description":"Facet aggregation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Facets"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitError"}}}},"/v1/vehicles":{"get":{"operationId":"listVehicles","summary":"List inventory (filterable, paginated)","description":"Paginated vehicle list. See query params for all documented filters. Default sort `auction_date_asc`. Source=dealer requires at least one of `make` or `model`.","parameters":[{"name":"make","in":"query","schema":{"type":"string"},"description":"CSV of makes, e.g., `Toyota,Honda`."},{"name":"model","in":"query","schema":{"type":"string"},"description":"Requires `make`."},{"name":"year_min","in":"query","schema":{"type":"integer"}},{"name":"year_max","in":"query","schema":{"type":"integer"}},{"name":"mileage_max_km","in":"query","schema":{"type":"integer"}},{"name":"price_min_usd","in":"query","schema":{"type":"integer"}},{"name":"price_max_usd","in":"query","schema":{"type":"integer"}},{"name":"source","in":"query","schema":{"type":"string"},"description":"CSV of source enum values."},{"name":"fuel","in":"query","schema":{"type":"string"},"description":"CSV of fuel tokens (case-insensitive)."},{"name":"transmission","in":"query","schema":{"type":"string"},"description":"CSV of transmission tokens. Accepts `auto`/`manual`/`cvt`/`dct` (mapped to data values) or raw `A/T`/`M/T`."},{"name":"accident_grade","in":"query","schema":{"type":"string"},"description":"CSV of A/B/C/D/F. Dealer rows (null grade) silently excluded — see `X-LMN-Filtered-Out` header."},{"name":"exterior_grade","in":"query","schema":{"type":"string"},"description":"CSV of A/B/C/D/F."},{"name":"options_include","in":"query","schema":{"type":"string"},"description":"CSV of snake_case option tokens (e.g., `sunroof,leather_seats`). AND semantics."},{"name":"auction_date_from","in":"query","schema":{"type":"string","format":"date"}},{"name":"auction_date_to","in":"query","schema":{"type":"string","format":"date"}},{"name":"auction_count_min","in":"query","schema":{"type":"integer"}},{"name":"auction_count_max","in":"query","schema":{"type":"integer"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["auction_date_asc","price_asc","price_desc","year_desc","mileage_asc"],"default":"auction_date_asc"}},{"$ref":"#/components/parameters/CursorParam"},{"$ref":"#/components/parameters/LimitParam"}],"responses":{"200":{"description":"Paginated list of vehicle summaries","headers":{"X-LMN-Filtered-Out":{"schema":{"type":"string","example":"dealer=3"},"description":"Set when auction-specific filters silently excluded rows (e.g., dealer)."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleList"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitError"}}}},"/v1/vehicles/{id}":{"get":{"operationId":"getVehicle","summary":"Vehicle detail","description":"Full vehicle detail including VIN, photos, body condition, inspection report, and price breakdown.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Vehicle detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleDetail"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"$ref":"#/components/responses/RateLimitError"}}}},"/v1/orders":{"post":{"operationId":"createOrder","summary":"Create an order","description":"Creates an order (=proceed) against a vehicle. For auctions, must be placed before `order_cutoff_at`. Replay the same Idempotency-Key to retrieve the original result.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrderRequest"}}}},"responses":{"200":{"description":"Idempotent replay — existing order returned unchanged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"201":{"description":"Order created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"},"409":{"description":"Conflict — `duplicate_order`, `past_order_cutoff`, or `invalid_status_transition`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Semantic error — e.g., `idempotency_key_reused` (key used previously with a different vehicle_id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimitError"}}},"get":{"operationId":"listOrders","summary":"List orders for the authenticated partner","parameters":[{"name":"ids","in":"query","schema":{"type":"string"},"description":"CSV, up to 100 order IDs."},{"name":"status","in":"query","schema":{"type":"string"},"description":"CSV of `OrderStatus` values."},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"},"description":"Lower bound on `created_at`. Requires `to`."},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["created_desc","created_asc","auction_date_asc","updated_desc"],"default":"created_desc"}},{"$ref":"#/components/parameters/CursorParam"},{"$ref":"#/components/parameters/LimitParam"}],"responses":{"200":{"description":"Paginated order list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderList"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitError"}}}},"/v1/orders/{id}":{"get":{"operationId":"getOrder","summary":"Order detail","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Order detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"$ref":"#/components/responses/RateLimitError"}}},"delete":{"operationId":"cancelOrder","summary":"Cancel an order","description":"Allowed only from `proceed` status. Sets `status=cancelled`, `cancellation_reason=dealer_cancelled`. Any other starting status returns `409 invalid_status_transition`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Order cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"},"409":{"$ref":"#/components/responses/ConflictError"},"429":{"$ref":"#/components/responses/RateLimitError"}}}},"/v1/orders/{id}/status":{"post":{"operationId":"pushOrderStatus","summary":"Push fulfillment/status update","description":"Partner-pushed status change. Only `status: delivered` (from `shipping`) and `fulfillment_detail` transitions are permitted.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusUpdateRequest"}}}},"responses":{"200":{"description":"Status updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"},"409":{"$ref":"#/components/responses/ConflictError"},"429":{"$ref":"#/components/responses/RateLimitError"}}}},"/v1/orders/{id}/events":{"get":{"operationId":"listOrderEvents","summary":"Order event history","description":"Chronological list of lifecycle events for the order. Useful as a poll-based alternative to webhooks.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Event list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderEventList"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"$ref":"#/components/responses/RateLimitError"}}}}}}