{"openapi":"3.1.0","info":{"title":"MotoSale Agent API","version":"1.4.0","description":"HTTP API for vehicle discovery and authenticated dealer inventory, statistics, calendar and conversations. The MCP server is an adapter over this API."},"servers":[{"url":"https://api.motosale.ch"}],"components":{"securitySchemes":{"supabaseBearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ListingFields":{"type":"object","additionalProperties":false,"description":"Editable listing fields. Omitted fields are unchanged on PATCH; explicit zero, false and nullable clears are preserved. Photos are managed in the MotoSale editor.","properties":{"title":{"type":"string","maxLength":160,"description":"Listing title; an omitted or empty draft title is generated from brand, model and year and must also fit 160 characters"},"description":{"type":["string","null"],"maxLength":10000,"description":"Listing description; null or an empty string clears it"},"brand":{"type":"string","maxLength":100,"description":"Manufacturer; known aliases are canonicalized","minLength":1},"model":{"type":["string","null"],"maxLength":100,"description":"Model; known aliases are canonicalized, custom model names are preserved; null clears it"},"year":{"type":"integer","minimum":1885,"maximum":2100,"description":"Manufacture year"},"price":{"type":"integer","minimum":0,"maximum":10000000,"description":"Price in CHF; zero is a value"},"mileage":{"type":"integer","minimum":0,"maximum":2000000,"description":"Kilometres; zero is a value"},"displacement":{"type":["integer","null"],"minimum":0,"maximum":10000,"description":"Engine displacement in cm³; null clears it"},"power":{"type":["integer","null"],"minimum":0,"maximum":2000,"description":"Power in metric PS; null clears it"},"fuel_type":{"type":"string","enum":["Benzin","Elektro","Diesel"],"description":"Canonical fuel type"},"transmission":{"type":"string","enum":["Manuell","Automatik","Halbautomatik"],"description":"Canonical transmission"},"color":{"type":["string","null"],"enum":["","Schwarz","Weiss","Grau","Silber","Rot","Blau","Grün","Gelb","Orange","Braun","Gold","Andere",null],"description":"Canonical colour; null or an empty string clears it"},"condition":{"type":"string","enum":["Neu","Occasion","Vorführmodell","Defekt"],"description":"Canonical vehicle condition"},"category":{"type":["string","null"],"enum":["Naked","Sport","Touring","Adventure","Enduro","Supermoto","Cross","Trial","Cruiser","Chopper","Classic","Andere","Roller","Grossroller","Mofa","Moped","Sportquad","Freizeit-Quad","Arbeits-ATV","Nutz-UTV","Sport-Side-by-Side","Dreirad/Trike","Beiwagen",null],"description":"Canonical subtype; null clears it on an unpublished draft"},"vehicle_type":{"type":"string","enum":["motorcycle","scooter","moped","quad_atv","utv","trike_sidecar"],"description":"Vehicle family; a category-only change derives its family"},"road_approval":{"type":["string","null"],"enum":["road","offroad",null],"description":"Road approval; null means unknown"},"drive_type":{"type":["string","null"],"enum":["2x4","4x4","6x6",null],"description":"Traction; null means unknown"},"seats":{"type":["integer","null"],"minimum":1,"maximum":10,"description":"Number of seats; null clears it"},"intended_use":{"type":["string","null"],"enum":["leisure","work","sport",null],"description":"Intended use; null means unknown"},"has_tow_hitch":{"type":["boolean","null"],"description":"Tow hitch: true present, false absent, null unknown"},"has_winch":{"type":["boolean","null"],"description":"Winch: true present, false absent, null unknown"},"payload_kg":{"type":["integer","null"],"minimum":0,"maximum":10000,"description":"Payload in kg; zero is a value, null clears it"},"canton":{"type":"string","maxLength":2,"description":"Swiss canton code or LI; lowercase is canonicalized","minLength":2},"city":{"type":["string","null"],"maxLength":100,"description":"Municipality; null or an empty string clears it"},"plz":{"type":"string","maxLength":10,"description":"Postal code; an empty string clears it"},"latitude":{"type":["number","null"],"minimum":-90,"maximum":90,"description":"Listing latitude; supply both coordinates or clear both with null"},"longitude":{"type":["number","null"],"minimum":-180,"maximum":180,"description":"Listing longitude; supply both coordinates or clear both with null"},"first_registration_date":{"type":["string","null"],"format":"date","description":"First registration as a real calendar date YYYY-MM-DD; null clears it"},"warranty_months":{"type":["integer","null"],"minimum":0,"maximum":120,"description":"Warranty months; zero means none, null clears it"},"has_service":{"type":"boolean","description":"Service flag; false does not delete a separately supplied historical date"},"last_service_date":{"type":["string","null"],"format":"date","description":"Latest service as a real calendar date YYYY-MM-DD; null clears it"},"has_mfk":{"type":"boolean","description":"MFK flag; false does not delete a separately supplied historical date"},"last_mfk_date":{"type":["string","null"],"format":"date","description":"Latest MFK as a real calendar date YYYY-MM-DD; null clears it"}}},"ListingDraft":{"type":"object","additionalProperties":false,"description":"Editable listing fields. Omitted fields are unchanged on PATCH; explicit zero, false and nullable clears are preserved. Photos are managed in the MotoSale editor.","properties":{"title":{"type":"string","maxLength":160,"description":"Listing title; an omitted or empty draft title is generated from brand, model and year and must also fit 160 characters"},"description":{"type":["string","null"],"maxLength":10000,"description":"Listing description; null or an empty string clears it"},"brand":{"type":"string","maxLength":100,"description":"Manufacturer; known aliases are canonicalized","minLength":1},"model":{"type":["string","null"],"maxLength":100,"description":"Model; known aliases are canonicalized, custom model names are preserved; null clears it"},"year":{"type":"integer","minimum":1885,"maximum":2100,"description":"Manufacture year"},"price":{"type":"integer","minimum":0,"maximum":10000000,"description":"Price in CHF; zero is a value"},"mileage":{"type":"integer","minimum":0,"maximum":2000000,"description":"Kilometres; zero is a value"},"displacement":{"type":["integer","null"],"minimum":0,"maximum":10000,"description":"Engine displacement in cm³; null clears it"},"power":{"type":["integer","null"],"minimum":0,"maximum":2000,"description":"Power in metric PS; null clears it"},"fuel_type":{"type":"string","enum":["Benzin","Elektro","Diesel"],"description":"Canonical fuel type"},"transmission":{"type":"string","enum":["Manuell","Automatik","Halbautomatik"],"description":"Canonical transmission"},"color":{"type":["string","null"],"enum":["","Schwarz","Weiss","Grau","Silber","Rot","Blau","Grün","Gelb","Orange","Braun","Gold","Andere",null],"description":"Canonical colour; null or an empty string clears it"},"condition":{"type":"string","enum":["Neu","Occasion","Vorführmodell","Defekt"],"description":"Canonical vehicle condition"},"category":{"type":["string","null"],"enum":["Naked","Sport","Touring","Adventure","Enduro","Supermoto","Cross","Trial","Cruiser","Chopper","Classic","Andere","Roller","Grossroller","Mofa","Moped","Sportquad","Freizeit-Quad","Arbeits-ATV","Nutz-UTV","Sport-Side-by-Side","Dreirad/Trike","Beiwagen",null],"description":"Canonical subtype; null clears it on an unpublished draft"},"vehicle_type":{"type":"string","enum":["motorcycle","scooter","moped","quad_atv","utv","trike_sidecar"],"description":"Vehicle family; a category-only change derives its family"},"road_approval":{"type":["string","null"],"enum":["road","offroad",null],"description":"Road approval; null means unknown"},"drive_type":{"type":["string","null"],"enum":["2x4","4x4","6x6",null],"description":"Traction; null means unknown"},"seats":{"type":["integer","null"],"minimum":1,"maximum":10,"description":"Number of seats; null clears it"},"intended_use":{"type":["string","null"],"enum":["leisure","work","sport",null],"description":"Intended use; null means unknown"},"has_tow_hitch":{"type":["boolean","null"],"description":"Tow hitch: true present, false absent, null unknown"},"has_winch":{"type":["boolean","null"],"description":"Winch: true present, false absent, null unknown"},"payload_kg":{"type":["integer","null"],"minimum":0,"maximum":10000,"description":"Payload in kg; zero is a value, null clears it"},"canton":{"type":"string","maxLength":2,"description":"Swiss canton code or LI; lowercase is canonicalized","minLength":2},"city":{"type":["string","null"],"maxLength":100,"description":"Municipality; null or an empty string clears it"},"plz":{"type":"string","maxLength":10,"description":"Postal code; an empty string clears it"},"latitude":{"type":["number","null"],"minimum":-90,"maximum":90,"description":"Listing latitude; supply both coordinates or clear both with null"},"longitude":{"type":["number","null"],"minimum":-180,"maximum":180,"description":"Listing longitude; supply both coordinates or clear both with null"},"first_registration_date":{"type":["string","null"],"format":"date","description":"First registration as a real calendar date YYYY-MM-DD; null clears it"},"warranty_months":{"type":["integer","null"],"minimum":0,"maximum":120,"description":"Warranty months; zero means none, null clears it"},"has_service":{"type":"boolean","description":"Service flag; false does not delete a separately supplied historical date"},"last_service_date":{"type":["string","null"],"format":"date","description":"Latest service as a real calendar date YYYY-MM-DD; null clears it"},"has_mfk":{"type":"boolean","description":"MFK flag; false does not delete a separately supplied historical date"},"last_mfk_date":{"type":["string","null"],"format":"date","description":"Latest MFK as a real calendar date YYYY-MM-DD; null clears it"}},"required":["brand","year","price","canton"]},"OwnedListing":{"type":"object","description":"Actual persisted editable values returned only to the authenticated owner after a write or idempotent replay. Unchanged historical values can differ from current input limits and catalogs. Public detail omits precise coordinates and private owner/contact metadata.","properties":{"title":{"type":"string"},"description":{"type":"string"},"brand":{"type":"string"},"model":{"type":"string"},"year":{"type":"integer"},"price":{"type":"integer"},"mileage":{"type":"integer"},"displacement":{"type":["integer","null"]},"power":{"type":["integer","null"]},"fuel_type":{"type":["string","null"]},"transmission":{"type":["string","null"]},"color":{"type":["string","null"]},"condition":{"type":["string","null"]},"category":{"type":["string","null"]},"vehicle_type":{"type":"string"},"road_approval":{"type":["string","null"]},"drive_type":{"type":["string","null"]},"seats":{"type":["integer","null"]},"intended_use":{"type":["string","null"]},"has_tow_hitch":{"type":["boolean","null"]},"has_winch":{"type":["boolean","null"]},"payload_kg":{"type":["integer","null"]},"canton":{"type":"string"},"city":{"type":["string","null"]},"plz":{"type":["string","null"]},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"first_registration_date":{"type":["string","null"],"format":"date"},"warranty_months":{"type":["integer","null"]},"has_service":{"type":"boolean"},"last_service_date":{"type":["string","null"],"format":"date"},"has_mfk":{"type":"boolean"},"last_mfk_date":{"type":["string","null"],"format":"date"},"id":{"type":"string","format":"uuid"},"status":{"type":["string","null"]},"is_active":{"type":["boolean","null"]},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"},"edit_url":{"type":"string","format":"uri"},"next_step":{"type":"string"},"idempotent_replay":{"type":"boolean"}}}}},"paths":{"/api/v1/me/access":{"get":{"operationId":"getDealerAccess","security":[{"supabaseBearer":[]}],"summary":"Read the authenticated dealer connection permissions","description":"Lists explicitly granted messages:read, messages:write, calendar:read and calendar:write capabilities. Existing OAuth connections receive none automatically. Manage permissions through the first-party manage_url. This endpoint cannot grant itself access.","responses":{"200":{"description":"Current user/client, granted capabilities, inventory access and browser management URL"},"401":{"description":"Authentication required"},"403":{"description":"Dealer account, verified email, active connection and live account required"}}}},"/api/v1/me/listings":{"get":{"operationId":"listMyListings","security":[{"supabaseBearer":[]}],"summary":"List and search only the authenticated dealer’s own listings, including drafts and every status","description":"The exact total and has_more refer to this owner and these filters. q matches title, brand or model, ignoring case, spaces and punctuation. model is a partial model filter; brand is an exact normalized brand filter. Omit status to include draft, active, inactive and sold.","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["draft","active","inactive","sold"]}},{"name":"q","in":"query","schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"brand","in":"query","schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"model","in":"query","schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"maximum":10000,"default":1}},{"name":"sort","in":"query","schema":{"type":"string","enum":["updated_desc","newest","price_asc","price_desc","title_asc"],"default":"updated_desc"}}],"responses":{"200":{"description":"Owned inventory and exact pagination","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"brand":{"type":"string"},"model":{"type":"string"},"year":{"type":"integer"},"price":{"type":"integer"},"mileage":{"type":"integer"},"displacement":{"type":["integer","null"]},"power":{"type":["integer","null"]},"fuel_type":{"type":["string","null"]},"transmission":{"type":["string","null"]},"color":{"type":["string","null"]},"condition":{"type":["string","null"]},"category":{"type":["string","null"]},"vehicle_type":{"type":"string"},"road_approval":{"type":["string","null"]},"drive_type":{"type":["string","null"]},"seats":{"type":["integer","null"]},"intended_use":{"type":["string","null"]},"has_tow_hitch":{"type":["boolean","null"]},"has_winch":{"type":["boolean","null"]},"payload_kg":{"type":["integer","null"]},"canton":{"type":"string"},"city":{"type":["string","null"]},"plz":{"type":["string","null"]},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"first_registration_date":{"type":["string","null"],"format":"date"},"warranty_months":{"type":["integer","null"]},"has_service":{"type":"boolean"},"last_service_date":{"type":["string","null"],"format":"date"},"has_mfk":{"type":"boolean"},"last_mfk_date":{"type":["string","null"],"format":"date"},"id":{"type":"string","format":"uuid"},"status":{"type":["string","null"]},"is_active":{"type":["boolean","null"]},"is_published":{"type":"boolean"},"image_urls":{"type":["array","null"],"items":{"type":"string"}},"draft_image_refs":{"type":["array","null"],"items":{"type":"string"},"description":"Private original references, not public download links"},"views":{"type":["integer","null"]},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]},"currency":{"const":"CHF"},"edit_url":{"type":"string","format":"uri"},"url":{"type":"string","format":"uri"}}}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"returned":{"type":"integer"},"has_more":{"type":"boolean"}}}}}}}},"400":{"description":"Invalid or unsupported filters"},"401":{"description":"Authentication required"},"403":{"description":"A live authorized dealer account is required"}}}},"/api/v1/me/listings/{id}":{"get":{"operationId":"getMyListing","security":[{"supabaseBearer":[]}],"summary":"Read one owned listing including unpublished fields and private photo references","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Owner-only listing details with editor link","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"brand":{"type":"string"},"model":{"type":"string"},"year":{"type":"integer"},"price":{"type":"integer"},"mileage":{"type":"integer"},"displacement":{"type":["integer","null"]},"power":{"type":["integer","null"]},"fuel_type":{"type":["string","null"]},"transmission":{"type":["string","null"]},"color":{"type":["string","null"]},"condition":{"type":["string","null"]},"category":{"type":["string","null"]},"vehicle_type":{"type":"string"},"road_approval":{"type":["string","null"]},"drive_type":{"type":["string","null"]},"seats":{"type":["integer","null"]},"intended_use":{"type":["string","null"]},"has_tow_hitch":{"type":["boolean","null"]},"has_winch":{"type":["boolean","null"]},"payload_kg":{"type":["integer","null"]},"canton":{"type":"string"},"city":{"type":["string","null"]},"plz":{"type":["string","null"]},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"first_registration_date":{"type":["string","null"],"format":"date"},"warranty_months":{"type":["integer","null"]},"has_service":{"type":"boolean"},"last_service_date":{"type":["string","null"],"format":"date"},"has_mfk":{"type":"boolean"},"last_mfk_date":{"type":["string","null"],"format":"date"},"id":{"type":"string","format":"uuid"},"status":{"type":["string","null"]},"is_active":{"type":["boolean","null"]},"is_published":{"type":"boolean"},"image_urls":{"type":["array","null"],"items":{"type":"string"}},"draft_image_refs":{"type":["array","null"],"items":{"type":"string"},"description":"Private original references, not public download links"},"views":{"type":["integer","null"]},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]},"currency":{"const":"CHF"},"edit_url":{"type":"string","format":"uri"},"url":{"type":"string","format":"uri"}}}}}}}},"400":{"description":"Invalid or unsupported filters"},"401":{"description":"Authentication required"},"403":{"description":"A live authorized dealer account is required"},"404":{"description":"Listing does not exist or is not owned by this dealer"}}}},"/api/v1/me/statistics":{"get":{"operationId":"getDealerStatistics","security":[{"supabaseBearer":[]}],"summary":"Own inventory by status, listing views and incoming inquiry counts","description":"Lifetime views use the stored cumulative listing counter. Period views count recorded view events, not unique visitors. Inquiries count distinct incoming threads by first received date, messages count individual received messages. Calendar days use Europe/Zurich; today ends at generated_at. Statistics never reveal message text or contact details. Inventory prices are asking prices, not realized sales revenue.","parameters":[{"name":"listing_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":365,"default":30}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"maximum":10000,"default":1}}],"responses":{"200":{"description":"Summary, daily series and paginated per-listing statistics","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["summary","period","daily","listings","meta"],"properties":{"summary":{"type":"object"},"period":{"type":"object"},"daily":{"type":"array","items":{"type":"object"}},"listings":{"type":"array","items":{"type":"object"}},"meta":{"type":"object"},"generated_at":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Invalid or unsupported filters"},"401":{"description":"Authentication required"},"403":{"description":"A live authorized dealer account is required"},"404":{"description":"Specified listing does not exist or is not owned"}}}},"/api/v1/me/test-rides":{"get":{"operationId":"listDealerTestRides","security":[{"supabaseBearer":[]}],"summary":"Read the authenticated dealer’s bookings and customer contact details","description":"Requires calendar:read. Defaults to next 31 days; maximum requested range 366 days. Returns only bookings for auth.uid(), with deterministic pagination and exact total.","parameters":[{"name":"listing_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO timestamp with explicit UTC offset; default next 31 days."},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO timestamp with explicit UTC offset; default next 31 days."},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":30}},{"name":"status","in":"query","schema":{"type":"string","enum":["confirmed","cancelled_by_buyer","cancelled_by_dealer"]}}],"responses":{"200":{"description":"data, meta and Europe/Zurich timezone"},"400":{"description":"Invalid settings, filter or range"},"401":{"description":"Authentication required"},"403":{"description":"Dealer account or calendar permission required"},"409":{"description":"Booked slot, overlap or retry-key conflict"}}}},"/api/v1/me/test-ride-slots":{"get":{"operationId":"getDealerCalendar","security":[{"supabaseBearer":[]}],"summary":"Read own calendar with available, booked, blocked and conflicting slots","description":"Requires calendar:read. Maximum range 93 days; customer contacts are available separately through bookings. Cross-vehicle booking conflicts are included.","parameters":[{"name":"listing_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO timestamp with explicit UTC offset; default next 31 days."},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO timestamp with explicit UTC offset; default next 31 days."},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":30}},{"name":"state","in":"query","schema":{"type":"string","enum":["available","booked","blocked","conflict","unavailable"]}}],"responses":{"200":{"description":"Owner-scoped slots with exact total and pagination"},"400":{"description":"Invalid settings, filter or range"},"401":{"description":"Authentication required"},"403":{"description":"Dealer account or calendar permission required"},"409":{"description":"Booked slot, overlap or retry-key conflict"}}},"post":{"operationId":"createTestRideSlots","security":[{"supabaseBearer":[]}],"summary":"Create a test-ride slot, optionally repeated weekly","description":"Requires calendar:write, an active owned listing and stable idempotency key. Local times are Europe/Zurich. Start within 30 days, finish within 89 days and allow at least 30 minutes before the slot starts. Nonexistent DST times are rejected; ambiguous times choose the standard-time occurrence. Existing overlaps are skipped.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"listing_id":{"type":"string","format":"uuid"},"day":{"type":"string","format":"date"},"local_time":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d(?::00)?$","description":"Local wall clock time in Europe/Zurich; DST is resolved by the database."},"duration_minutes":{"type":"integer","enum":[30,45,60,90],"default":45},"weeks":{"type":"integer","minimum":1,"maximum":4,"default":1},"idempotency_key":{"type":"string","format":"uuid"}},"required":["listing_id","day","local_time","idempotency_key"]}}}},"responses":{"200":{"description":"Original result for an exact retry"},"201":{"description":"Created/skipped counts and up to 50 created slot IDs"},"400":{"description":"Invalid settings, filter or range"},"401":{"description":"Authentication required"},"403":{"description":"Dealer account or calendar permission required"},"409":{"description":"Booked slot, overlap or retry-key conflict"}}}},"/api/v1/me/test-ride-slots/bulk":{"post":{"operationId":"bulkCreateTestRideSlots","security":[{"supabaseBearer":[]}],"summary":"Create recurring weekday availability for several owned listings","description":"Requires calendar:write. Weekdays 1=Monday through 7=Sunday, Europe/Zurich. Up to 30 listings, 12 weeks and 10000 candidate slots. Start within 30 days, finish within 89 days and allow at least 30 minutes before any slot starts. Existing overlaps and nonexistent DST times are skipped and reported.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"listing_ids":{"type":"array","minItems":1,"maxItems":30,"uniqueItems":true,"items":{"type":"string","format":"uuid"}},"weekdays":{"type":"array","minItems":1,"maxItems":7,"uniqueItems":true,"items":{"type":"integer","minimum":1,"maximum":7}},"start_date":{"type":"string","format":"date"},"start_time":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d(?::00)?$","description":"Local wall clock time in Europe/Zurich; DST is resolved by the database."},"end_time":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d(?::00)?$","description":"Local wall clock time in Europe/Zurich; DST is resolved by the database."},"duration_minutes":{"type":"integer","enum":[30,45,60,90],"default":45},"weeks":{"type":"integer","minimum":1,"maximum":12,"default":1},"idempotency_key":{"type":"string","format":"uuid"}},"required":["listing_ids","weekdays","start_date","start_time","end_time","idempotency_key"]}}}},"responses":{"200":{"description":"Idempotent replay"},"201":{"description":"Created/skipped counts with at most 50 created slot IDs"},"400":{"description":"Invalid settings, filter or range"},"401":{"description":"Authentication required"},"403":{"description":"Dealer account or calendar permission required"},"409":{"description":"Booked slot, overlap or retry-key conflict"}}}},"/api/v1/me/test-ride-slots/{id}":{"patch":{"operationId":"updateTestRideSlot","security":[{"supabaseBearer":[]}],"summary":"Move or block/unblock an unbooked owned calendar slot","description":"Requires calendar:write. To move a slot supply all of day, local_time and duration_minutes. Confirmed bookings cannot be moved or blocked. Cancel with explicit customer-notification authorization, then have the buyer choose and confirm a new slot.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"day":{"type":"string","format":"date"},"local_time":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d(?::00)?$","description":"Local wall clock time in Europe/Zurich; DST is resolved by the database."},"duration_minutes":{"type":"integer","enum":[30,45,60,90],"default":45},"blocked":{"type":"boolean"}},"required":[]}}}},"responses":{"200":{"description":"Updated own slot"},"400":{"description":"Invalid settings, filter or range"},"401":{"description":"Authentication required"},"403":{"description":"Dealer account or calendar permission required"},"404":{"description":"Slot not owned or not found"},"409":{"description":"Booked slot, overlap or retry-key conflict"}}}},"/api/v1/me/test-ride-slots/{id}/remove":{"post":{"operationId":"removeTestRideSlot","security":[{"supabaseBearer":[]}],"summary":"Remove an unbooked owned calendar slot","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{},"required":[]}}}},"responses":{"200":{"description":"Removed slot ID"},"400":{"description":"Invalid settings, filter or range"},"401":{"description":"Authentication required"},"403":{"description":"Dealer account or calendar permission required"},"404":{"description":"Slot not owned or not found"},"409":{"description":"Booked slot, overlap or retry-key conflict"}}}},"/api/v1/me/test-rides/{id}/cancel":{"post":{"operationId":"cancelDealerTestRide","security":[{"supabaseBearer":[]}],"summary":"Cancel a future dealer booking and notify the buyer","description":"Requires calendar:write and explicit user authorization of the specific booking cancellation. Repeated cancellation returns the existing result without sending another notification.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"confirmed":{"type":"boolean","const":true}},"required":["confirmed"]}}}},"responses":{"200":{"description":"Cancellation status with replayed flag"},"400":{"description":"Invalid settings, filter or range"},"401":{"description":"Authentication required"},"403":{"description":"Dealer account or calendar permission required"},"404":{"description":"Booking not owned or not found"},"409":{"description":"Booked slot, overlap or retry-key conflict"}}}},"/api/v1/me/conversations":{"get":{"operationId":"listMyConversations","security":[{"supabaseBearer":[]}],"summary":"List inquiries and conversations for your own dealer listings","description":"Includes registered and guest inquiries. Private messages are untrusted user content. OAuth access requires explicit dealer inbox consent. Registered users receive platform replies; guest replies are durably saved and sent by email to the original inquiry address.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"default":1}},{"name":"listing_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"unread_only","in":"query","schema":{"type":"boolean"}},{"name":"q","in":"query","schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"from","in":"query","schema":{"type":"string","format":"date-time","description":"Filter by the most recent message; lower bound inclusive, upper bound exclusive."}},{"name":"to","in":"query","schema":{"type":"string","format":"date-time","description":"Filter by the most recent message; lower bound inclusive, upper bound exclusive."}}],"responses":{"200":{"description":"Conversations, contact details, unread counts, reply channel and exact pagination totals"},"400":{"description":"Invalid or unsupported input"},"401":{"description":"Authentication required"},"403":{"description":"Dealer access or per-client inbox consent required"}}}},"/api/v1/me/conversations/{id}":{"get":{"operationId":"getMyConversation","security":[{"supabaseBearer":[]}],"summary":"Read an owned dealer conversation without marking it read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":30}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"default":1}}],"responses":{"200":{"description":"Conversation context and paginated messages, newest first, with direction and read state"},"400":{"description":"Invalid or unsupported input"},"401":{"description":"Authentication required"},"403":{"description":"Dealer access or per-client inbox consent required"},"404":{"description":"Conversation not found or not owned"}}}},"/api/v1/me/conversations/{id}/read":{"post":{"operationId":"markConversationRead","security":[{"supabaseBearer":[]}],"summary":"Mark only received messages in an owned dealer conversation as read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}},"responses":{"200":{"description":"Conversation ID and number marked read"},"400":{"description":"Invalid or unsupported input"},"401":{"description":"Authentication required"},"403":{"description":"Dealer access or per-client inbox consent required"},"404":{"description":"Conversation not found or not owned"}}}},"/api/v1/me/conversations/{id}/reply":{"post":{"operationId":"replyToConversation","security":[{"supabaseBearer":[]}],"summary":"Send a confirmed reply to a buyer in an existing owned conversation","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"description":"The recipient is derived from the owned conversation; caller-supplied recipients are forbidden. Explicit user approval of recipient and exact message is required. Reuse one idempotency key with exactly the same conversation and text on retries. Guest replies use the original inquiry email address and a durable outbox. Read delivery_status: pending/sending/failed/uncertain do not mean sent. Uncertain deliveries are never automatically retried beyond the provider deduplication window.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["message","confirmed","idempotency_key"],"properties":{"message":{"type":"string","minLength":1,"maxLength":5000},"confirmed":{"const":true},"idempotency_key":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Existing reply returned without duplication"},"201":{"description":"Platform reply saved or guest email sent; delivery channel and status are explicit"},"202":{"description":"Guest reply saved but email delivery is pending, failed or uncertain; inspect delivery_status and never report it as sent"},"400":{"description":"Invalid or unsupported input"},"401":{"description":"Authentication required"},"403":{"description":"Dealer access or per-client inbox consent required"},"404":{"description":"Conversation not found or not owned"},"409":{"description":"Recipient unavailable or idempotency key conflicts"},"429":{"description":"Message rate limit reached"}}}},"/api/v1/taxonomy":{"get":{"operationId":"getVehicleTaxonomy","summary":"Canonical vehicle families and subcategories, translated labels and stable category values","responses":{"200":{"description":"Vehicle taxonomy with locale labels"}}}},"/api/v1/brands":{"get":{"operationId":"getVehicleBrands","summary":"Get the canonical manufacturer catalog","responses":{"200":{"description":"Manufacturers with available catalog models"}}}},"/api/v1/models":{"get":{"operationId":"getBrandModels","summary":"Get canonical model catalog for a given brand; optionally filter by query","parameters":[{"name":"brand","in":"query","required":true,"schema":{"type":"string","maxLength":120},"description":"Canonical manufacturer or alias (e.g. QJ Motor)"},{"name":"q","in":"query","schema":{"type":"string","maxLength":100},"description":"Optional partial model search (case and punctuation insensitive)"}],"responses":{"200":{"description":"Brand, canonical models, count, matching query"},"400":{"description":"Invalid or unknown brand"}}}},"/api/v1/motorcycles":{"get":{"operationId":"searchMotorcycles","summary":"Search active motorcycles in Switzerland","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"brand","in":"query","schema":{"type":"string"}},{"name":"model","in":"query","schema":{"type":"string"}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"vehicle_type","in":"query","schema":{"type":"string"}},{"name":"fuel_type","in":"query","schema":{"type":"string"}},{"name":"road_approval","in":"query","schema":{"type":"string"}},{"name":"drive_type","in":"query","schema":{"type":"string"}},{"name":"intended_use","in":"query","schema":{"type":"string"}},{"name":"seats","in":"query","schema":{"type":"integer"}},{"name":"payload_kg_min","in":"query","schema":{"type":"integer"}},{"name":"has_tow_hitch","in":"query","schema":{"type":"boolean"}},{"name":"has_winch","in":"query","schema":{"type":"boolean"}},{"name":"has_service","in":"query","schema":{"type":"boolean"}},{"name":"has_mfk","in":"query","schema":{"type":"boolean"}},{"name":"has_warranty","in":"query","schema":{"type":"boolean"}},{"name":"canton","in":"query","schema":{"type":"string"}},{"name":"condition","in":"query","schema":{"type":"string"}},{"name":"price_min","in":"query","schema":{"type":"integer"}},{"name":"price_max","in":"query","schema":{"type":"integer"}},{"name":"year_min","in":"query","schema":{"type":"integer"}},{"name":"year_max","in":"query","schema":{"type":"integer"}},{"name":"mileage_max","in":"query","schema":{"type":"integer"}},{"name":"power_min","in":"query","schema":{"type":"integer"}},{"name":"power_max","in":"query","schema":{"type":"integer"}},{"name":"displacement_min","in":"query","schema":{"type":"integer"}},{"name":"displacement_max","in":"query","schema":{"type":"integer"}},{"name":"latitude","in":"query","schema":{"type":"number"}},{"name":"longitude","in":"query","schema":{"type":"number"}},{"name":"radius_km","in":"query","schema":{"type":"integer"}},{"name":"lat","in":"query","schema":{"type":"number"}},{"name":"lng","in":"query","schema":{"type":"number"}},{"name":"radius","in":"query","schema":{"type":"integer"}},{"name":"sort","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"page","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Active matching listings"}}}},"/api/v1/motorcycles/{id}":{"get":{"operationId":"getMotorcycle","summary":"Get one active listing","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Public motorcycle details, including first registration/service/MFK dates. Precise coordinates and private owner/contact metadata are omitted."}}}},"/api/v1/test-rides/availability":{"get":{"operationId":"getTestRideAvailability","summary":"Free, immediately bookable dealer test ride slots","responses":{"200":{"description":"Available slots in Europe/Zurich"}}}},"/api/v1/test-rides/book":{"post":{"operationId":"bookTestRide","security":[{"supabaseBearer":[]}],"summary":"Book an exact available slot with explicit confirmation and an idempotency key","responses":{"201":{"description":"Confirmed booking"}}}},"/api/v1/test-rides/{id}/cancel":{"post":{"operationId":"cancelTestRide","security":[{"supabaseBearer":[]}],"summary":"Cancel your upcoming test ride","responses":{"200":{"description":"Cancelled booking"}}}},"/api/v1/test-rides":{"post":{"operationId":"requestTestRide","security":[{"supabaseBearer":[]}],"summary":"Request a dealer test ride, pending confirmation","responses":{"201":{"description":"Request saved and forwarded to dealer inbox"}}}},"/api/v1/listings/drafts":{"post":{"operationId":"createListingDraft","security":[{"supabaseBearer":[]}],"summary":"Create a dealer-owned draft","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","format":"uuid"},"description":"Reuse the same UUID when retrying draft creation"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingDraft"}}}},"responses":{"200":{"description":"Existing draft fields for an idempotent retry","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/OwnedListing"}}}}}},"201":{"description":"Persisted draft fields with photo editor URL","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/OwnedListing"}}}}}}}}},"/api/v1/listings/{id}":{"patch":{"operationId":"updateListing","security":[{"supabaseBearer":[]}],"summary":"Edit your own dealer listing; OAuth edits are limited to unpublished drafts/inactive listings","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingFields"}}}},"responses":{"200":{"description":"Actual persisted editable fields after update","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/OwnedListing"}}}}}}}}},"/api/v1/listings/{id}/photos/import":{"post":{"operationId":"importListingPhotos","security":[{"supabaseBearer":[]}],"summary":"Import private JPEG, PNG or static WebP originals into your own draft or inactive listing","description":"Appends up to ten photos in order; the gallery has a ten-photo total limit. Each photo is limited to 25 MiB and 50 megapixels. A stable UUID binds the complete ordered URL list. Retry that exact list and key after temporary errors. Processing pauses at the first failed photo to preserve order. HTTP 200 may contain partial or failed results: inspect every item. The listing stays unpublished; review and finalize photos in the MotoSale editor.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["image_urls","idempotency_key"],"properties":{"image_urls":{"type":"array","minItems":1,"maxItems":10,"uniqueItems":true,"items":{"type":"string","format":"uri","maxLength":2048,"pattern":"^https://"},"description":"Public HTTPS image URLs; no credentials, IP literals, private destinations or custom ports"},"idempotency_key":{"type":"string","format":"uuid","description":"Reuse the same UUID with the same ordered URLs to resume without duplicates"}}}}}},"responses":{"200":{"description":"Processed batch, including per-photo errors and paused items; private originals are never publicly exposed","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["listing_id","idempotency_key","status","image_count","results","edit_url","next_step"],"properties":{"listing_id":{"type":"string","format":"uuid"},"idempotency_key":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["complete","partial","failed"]},"image_count":{"type":"integer","minimum":0,"maximum":10},"results":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"object","required":["index","image_id","status"],"properties":{"index":{"type":"integer","minimum":0,"maximum":9},"image_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["imported","already_present","failed"]},"error":{"type":"string"},"retryable":{"type":"boolean"}}}},"edit_url":{"type":"string","format":"uri"},"next_step":{"type":"string"}}}}}}}},"400":{"description":"Invalid URL list, duplicate URLs or idempotency key"},"401":{"description":"Authentication required"},"403":{"description":"Active dealer account required"},"404":{"description":"Listing not found or not owned"},"409":{"description":"Listing is public/sold, gallery limit exceeded, or idempotency key reused with different URLs"},"429":{"description":"New import request limit reached"}}}},"/api/v1/listings/{id}/publish":{"post":{"operationId":"publishListing","security":[{"supabaseBearer":[]}],"summary":"Publish after explicit confirmation, finalized photos and OAuth browser approval","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["confirmed"],"properties":{"confirmed":{"type":"boolean","const":true},"approval_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Published listing"},"409":{"description":"OAuth action requires a single-use human browser approval; open approval_url and retry with approval_id"}}}},"/api/v1/listings/{id}/status":{"post":{"operationId":"updateListingStatus","security":[{"supabaseBearer":[]}],"summary":"Mark own listing sold or inactive after OAuth browser approval","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["status"],"properties":{"status":{"type":"string","enum":["sold","inactive"]},"approval_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Updated status"},"409":{"description":"OAuth action requires a single-use human browser approval; open approval_url and retry with approval_id"}}}}}}