{"openapi":"3.0.0","info":{"title":"Furniture Department Commerce API","version":"1.0.0","description":"REST API for product discovery, cart management, and checkout. Optimized for LLM integrations including ChatGPT ACP and Claude MCP.","contact":{"email":"api@furnituredepartment.com"}},"servers":[{"url":"https://www.fdt-dev.com","description":"Production server"}],"paths":{"/api/products/search":{"get":{"summary":"Search products","description":"Search and filter furniture products with semantic search, faceted filtering, and sorting.","parameters":[{"name":"q","in":"query","description":"Search query (supports semantic search)","schema":{"type":"string"},"example":"modern gray sofa"},{"name":"category","in":"query","description":"Filter by category slug","schema":{"type":"string"},"example":"sofas-couches"},{"name":"min_price","in":"query","description":"Minimum price in cents","schema":{"type":"integer"},"example":50000},{"name":"max_price","in":"query","description":"Maximum price in cents","schema":{"type":"integer"},"example":200000},{"name":"sort","in":"query","description":"Sort order","schema":{"type":"string","enum":["relevance","price_asc","price_desc","newest","rating"]},"example":"relevance"},{"name":"limit","in":"query","description":"Number of results per page (max 100)","schema":{"type":"integer","default":20,"maximum":100}},{"name":"offset","in":"query","description":"Pagination offset","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}}}}},"/api/products/{slug}":{"get":{"summary":"Get product details","description":"Retrieve complete information about a specific product including images, specifications, reviews, and availability.","parameters":[{"name":"slug","in":"path","required":true,"description":"Product slug identifier","schema":{"type":"string"},"example":"modern-gray-sectional-sofa"}],"responses":{"200":{"description":"Product found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductDetail"}}}},"404":{"description":"Product not found"}}}},"/api/categories":{"get":{"summary":"List all categories","description":"Get furniture categories with product counts and hierarchical structure.","responses":{"200":{"description":"Categories list","content":{"application/json":{"schema":{"type":"object","properties":{"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}}}}}}}}},"/api/cart":{"get":{"summary":"Get cart contents","description":"Retrieve current shopping cart with line items and totals. Requires authentication.","security":[{"cookieAuth":[]}],"responses":{"200":{"description":"Cart retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cart"}}}},"401":{"description":"Unauthorized - user must be logged in"}}},"post":{"summary":"Add item to cart","description":"Add a product to the shopping cart. Creates cart if none exists.","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["product_id","quantity"],"properties":{"product_id":{"type":"string","format":"uuid","description":"Product UUID"},"quantity":{"type":"integer","minimum":1,"description":"Quantity to add"},"variant_id":{"type":"string","format":"uuid","description":"Optional product variant UUID"}}}}}},"responses":{"200":{"description":"Item added to cart","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cart"}}}},"400":{"description":"Invalid request"},"401":{"description":"Unauthorized"}}}},"/api/checkout/create-payment-intent":{"post":{"summary":"Create checkout session","description":"Initialize checkout with Stripe payment intent. Returns client secret for frontend payment confirmation.","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["shipping_address"],"properties":{"shipping_address":{"type":"object","required":["line1","city","state","postal_code","country"],"properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string","default":"US"}}},"billing_address":{"type":"object","description":"Optional billing address (uses shipping if not provided)"}}}}}},"responses":{"200":{"description":"Payment intent created","content":{"application/json":{"schema":{"type":"object","properties":{"clientSecret":{"type":"string"},"paymentIntentId":{"type":"string"}}}}}}}}},"/api/orders/create":{"post":{"summary":"Complete order","description":"Finalize order after successful payment. Called automatically after Stripe confirmation.","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["payment_intent_id"],"properties":{"payment_intent_id":{"type":"string","description":"Stripe payment intent ID"}}}}}},"responses":{"200":{"description":"Order created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}}}}}},"components":{"securitySchemes":{"cookieAuth":{"type":"apiKey","in":"cookie","name":"sb-access-token","description":"Supabase session cookie (automatically set after authentication)"}},"schemas":{"Product":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string"},"price_cents":{"type":"integer","description":"Price in cents (USD)"},"compare_at_price_cents":{"type":"integer","nullable":true},"brand":{"type":"string"},"in_stock":{"type":"boolean"},"average_rating":{"type":"number","nullable":true},"product_images":{"type":"array","items":{"type":"object","properties":{"image_url":{"type":"string"},"alt_text":{"type":"string"},"is_primary":{"type":"boolean"}}}},"manufacturers":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"}}},"product_categories":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"}}}}},"ProductDetail":{"allOf":[{"$ref":"#/components/schemas/Product"},{"type":"object","properties":{"long_description":{"type":"string"},"specifications":{"type":"object"},"dimensions":{"type":"object"},"materials":{"type":"array","items":{"type":"string"}},"care_instructions":{"type":"string"},"warranty_years":{"type":"integer"},"review_count":{"type":"integer"}}}]},"Category":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string"},"product_count":{"type":"integer"},"children":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}}},"Cart":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"items":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string","format":"uuid"},"product_name":{"type":"string"},"quantity":{"type":"integer"},"unit_price_cents":{"type":"integer"},"subtotal_cents":{"type":"integer"}}}},"subtotal_cents":{"type":"integer"},"tax_cents":{"type":"integer"},"shipping_cents":{"type":"integer"},"total_cents":{"type":"integer"}}},"Order":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"order_number":{"type":"string"},"status":{"type":"string","enum":["pending","confirmed","shipped","delivered","cancelled"]},"items":{"type":"array"},"total_cents":{"type":"integer"},"shipping_address":{"type":"object"},"tracking_number":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}}}},"tags":[{"name":"Products","description":"Product discovery and details"},{"name":"Cart","description":"Shopping cart management"},{"name":"Checkout","description":"Payment and order completion"}]}