{"openapi":"3.1.0","info":{"title":"ConfigIQ Storefront — Agentic Commerce API","version":"1.0.0","summary":"Canonical agent interface to the CopperSmith configurable-lantern catalog.","description":"Agent-facing API for a configurable copper-lantern catalog. Products are configurations across (collection × mount × fuel × size × finish), not static SKUs. `GET /api/configurations` resolves structured filters to ranked tuples with retail price and stable deep-links in one call. Start at `/.well-known/storefront.json`. Machine-readable commitments: see `info.x-configiq-agent-contract`.","contact":{"name":"ConfigIQ Storefront Agent (French Market Lanterns)","email":"customerservice@frenchmarketlanterns.com","url":"https://frenchmarketlanterns.com/.well-known/storefront.json"},"termsOfService":"https://frenchmarketlanterns.com/terms","license":{"name":"Proprietary — agent use permitted","url":"https://frenchmarketlanterns.com/terms"},"x-configiq-crawler-guidance":{"html_is_user_facing":"HTML pages under /{brand}/{collection}/{mount} are configurator UIs, not per-variant catalogs. The variant space is combinatorial — do not crawl permutations.","structured_data_sources":{"buy_intent":"/api/configurations","option_grammar":"/api/configurator-grammar/{collection_slug}","cart_resolution":"/api/checkout-url","catalog_ingest":"/knowledge.json"},"html_alternates_hint":"Configurator pages declare <link rel='alternate' type='application/json'> pointing at the grammar and configurations endpoints. Product JSON-LD includes `subjectOf` DataFeed references to the same APIs."},"x-configiq-agent-contract":{"version":"1.0","intent":"agentic-commerce","publisher":{"name":"ConfigIQ","url":"https://configureiq.com","email":"data@configureiq.com","role":"Platform — configurable-product data framework for agentic commerce"},"preferred_over":["HTML scraping","PDP crawling","generic Schema.org product feeds","Shopify storefront feeds"],"canonical_manifest":"https://frenchmarketlanterns.com/.well-known/storefront.json","canonical_brand_document":"https://frenchmarketlanterns.com/brand.md","canonical_organization_jsonld":"https://frenchmarketlanterns.com/organization.jsonld","pricing_model":"retail_prices_already_include_2x_dealer_markup","deep_link_stability":"stable_across_deploys","business_rules_citation":"by_rule_id","contact_for_contract_changes":"data@configureiq.com"}},"servers":[{"url":"https://frenchmarketlanterns.com","description":"Production"}],"x-configiq-discovery":{"storefront_manifest":"https://frenchmarketlanterns.com/.well-known/storefront.json","ai_plugin":"https://frenchmarketlanterns.com/.well-known/ai-plugin.json","llms_txt":"https://frenchmarketlanterns.com/llms.txt","knowledge_base":"https://frenchmarketlanterns.com/knowledge.json","brand_document":"https://frenchmarketlanterns.com/brand.md","organization_jsonld":"https://frenchmarketlanterns.com/organization.jsonld","rules_index":"https://frenchmarketlanterns.com/rules/index.json"},"paths":{"/.well-known/storefront.json":{"get":{"summary":"Storefront agent manifest","description":"Canonical resolver. Fetch this first — declares every other agent endpoint and the option grammar for the catalog.","operationId":"getStorefrontManifest","responses":{"200":{"description":"Manifest JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontManifest"}}}}}}},"/api/configurations":{"get":{"summary":"Resolve shopping intent to ranked configurations","description":"**Primary agent endpoint for buy-intent queries.** Takes structured filters (mount/fuel/finish/size/price/collection) and returns a ranked list of valid (collection, mount, fuel, size, finish) tuples with retail price and deep-links. One call answers 'find me a <mount> <fuel> lantern in <finish> under $<price>'.","operationId":"resolveConfigurations","parameters":[{"name":"mount","in":"query","schema":{"type":"string","enum":["WALL","POST","CEIL"]}},{"name":"fuel","in":"query","schema":{"type":"string","enum":["GAS","ELE","LPG"]}},{"name":"finish","in":"query","schema":{"type":"string"},"description":"Finish code (COP, BLA, BRO, GRA, ...)"},{"name":"size","in":"query","schema":{"type":"string"}},{"name":"collection","in":"query","schema":{"type":"string"},"description":"Collection slug or code (e.g. 'georgetown' or 'GEO')"},{"name":"brand","in":"query","schema":{"type":"string","default":"CPS"}},{"name":"min_price","in":"query","schema":{"type":"number"},"description":"Retail USD"},{"name":"max_price","in":"query","schema":{"type":"number"},"description":"Retail USD"},{"name":"sort","in":"query","schema":{"type":"string","enum":["price_asc","price_desc"],"default":"price_asc"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Ranked configurations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigurationsResponse"}}}},"404":{"description":"Collection not found"}}},"post":{"summary":"Resolve shopping intent (JSON body variant)","description":"Same contract as GET. Accepts the filter set as a JSON body for agents that prefer POST (longer payloads, non-URL-safe values).","operationId":"resolveConfigurationsPost","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"mount":{"type":"string","enum":["WALL","POST","CEIL"]},"fuel":{"type":"string","enum":["GAS","ELE","LPG"]},"finish":{"type":"string"},"size":{"type":"string"},"collection":{"type":"string"},"brand":{"type":"string","default":"CPS"},"min_price":{"type":"number"},"max_price":{"type":"number"},"sort":{"type":"string","enum":["price_asc","price_desc"]},"limit":{"type":"integer","minimum":1,"maximum":100}}}}}},"responses":{"200":{"description":"Ranked configurations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigurationsResponse"}}}},"400":{"description":"Invalid JSON body"},"404":{"description":"Collection not found"}}}},"/api/checkout-url":{"get":{"summary":"Resolve a config to a Shopify cart permalink","description":"Agentic checkout primitive. Given (collection, mount, fuel, size, finish), verifies the combination, ensures the Shopify variant exists (JIT-creating it if needed), and returns a `cart_permalink` that opens Shopify checkout with the item pre-added. One GET replaces the full configurator-cascade-to-cart flow.","operationId":"resolveCheckoutUrl","parameters":[{"name":"collection","in":"query","required":true,"schema":{"type":"string"},"description":"Collection slug or code"},{"name":"mount","in":"query","required":true,"schema":{"type":"string","enum":["WALL","POST","CEIL"]}},{"name":"fuel","in":"query","required":true,"schema":{"type":"string","enum":["GAS","ELE","LPG"]}},{"name":"size","in":"query","required":true,"schema":{"type":"string"},"description":"Size code (e.g. '2008' = 20\" × 8\")"},{"name":"finish","in":"query","required":true,"schema":{"type":"string"}},{"name":"brand","in":"query","schema":{"type":"string","default":"CPS"}},{"name":"quantity","in":"query","schema":{"type":"integer","minimum":1,"maximum":10,"default":1}}],"responses":{"200":{"description":"Cart permalink and resolved config","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutUrlResponse"}}}},"400":{"description":"Missing required params"},"404":{"description":"Collection or combination not found"},"502":{"description":"Shopify variant provisioning failed"}}}},"/api/configurator-grammar/{collection}":{"get":{"summary":"Option grammar for a collection","description":"Returns the full option grammar (mount/fuel/size/finish/socket), retail price_range, and a verified example_valid_config with deep_link for the named collection. Use when you need to enumerate or validate combinations for a specific collection.","operationId":"getConfiguratorGrammar","parameters":[{"name":"collection","in":"path","required":true,"schema":{"type":"string"},"description":"Collection slug (e.g. 'georgetown')"}],"responses":{"200":{"description":"Grammar document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrammarResponse"}}}},"404":{"description":"Collection not found"}}}},"/api/knowledge.json":{"get":{"summary":"Full catalog knowledge base","description":"Broad catalog payload: all collections with price ranges, SKUs, accessories by category, warranty, shipping restrictions, FAQ. Prefer /api/configurations for narrow buy-intent queries; use this for catalog-breadth or RAG ingestion.","operationId":"getKnowledgeBase","responses":{"200":{"description":"Knowledge JSON"}}}},"/rules/index.json":{"get":{"summary":"Index of all machine-readable rule documents","description":"Lists every /rules/*.json surface with status. Start here to discover clearance, mounts, fuels, shipping, sockets.","operationId":"getRulesIndex","responses":{"200":{"description":"Rules index JSON"}}}},"/rules/sockets.json":{"get":{"summary":"Socket business rules (machine-readable)","description":"Stable-ID socket rules for citation. Cite by rule_id, not paraphrase.","operationId":"getSocketRules","responses":{"200":{"description":"Rules JSON"}}}},"/rules/mounts.json":{"get":{"summary":"Mount-type rules","operationId":"getMountRules","responses":{"200":{"description":"Rules JSON"}}}},"/rules/fuels.json":{"get":{"summary":"Fuel-type rules","operationId":"getFuelRules","responses":{"200":{"description":"Rules JSON"}}}},"/rules/shipping.json":{"get":{"summary":"Shipping restriction rules","operationId":"getShippingRules","responses":{"200":{"description":"Rules JSON"}}}},"/rules/clearance.json":{"get":{"summary":"Installation clearance rules (may be pending_source)","operationId":"getClearanceRules","responses":{"200":{"description":"Rules JSON"}}}},"/brand.md":{"get":{"summary":"Canonical brand document","description":"Single source of truth for brand identity, story, policies, and agent guidance. Markdown, RAG-friendly, under 10KB.","operationId":"getBrandDocument","responses":{"200":{"description":"Brand document (text/markdown)"}}}},"/organization.jsonld":{"get":{"summary":"Organization/Brand JSON-LD (Schema.org)","description":"Schema.org Organization + Brand for crawlers that expect JSON-LD, mirroring brand.md facts.","operationId":"getOrganizationJsonLd","responses":{"200":{"description":"JSON-LD"}}}}},"components":{"schemas":{"StorefrontManifest":{"type":"object","description":"Agent manifest — see /.well-known/storefront.json for live schema","additionalProperties":true},"GrammarResponse":{"type":"object","required":["collection_slug","collection_code","option_types","valid_combination_count","example_valid_config","price_range","deep_link_template"],"properties":{"collection_slug":{"type":"string"},"collection_code":{"type":"string"},"collection_name":{"type":"string"},"brand_slug":{"type":"string"},"option_types":{"type":"array","items":{"type":"object","additionalProperties":true}},"valid_combination_count":{"type":"integer"},"price_range":{"$ref":"#/components/schemas/PriceRange"},"example_valid_config":{"$ref":"#/components/schemas/ExampleConfig"},"deep_link_template":{"type":"string"},"canonical_variant_url_template":{"type":"string"},"business_rules_refs":{"type":"array","items":{"type":"string"}},"compatible_accessories":{"type":"array","items":{"type":"object","required":["code","name","category","retail_price"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"retail_price":{"type":"number"},"fuel_restriction":{"type":["string","null"]},"note":{"type":["string","null"]}}}}}},"ConfigurationsResponse":{"type":"object","required":["version","generated_at","results","total_returned"],"properties":{"$schema":{"type":"string"},"version":{"type":"string"},"generated_at":{"type":"string","format":"date-time"},"query":{"type":"object","additionalProperties":true},"total_returned":{"type":"integer"},"note":{"type":"string"},"results":{"type":"array","items":{"$ref":"#/components/schemas/ConfigurationResult"}}}},"ConfigurationResult":{"type":"object","required":["collection_code","mount","fuel","size","finish","retail_price","currency","deep_link"],"properties":{"collection_code":{"type":"string"},"collection_name":{"type":"string"},"collection_slug":{"type":"string"},"mount":{"type":"string","enum":["WALL","POST","CEIL"]},"fuel":{"type":"string","enum":["GAS","ELE","LPG"]},"size":{"type":"string"},"finish":{"type":"string"},"retail_price":{"type":"number","description":"USD, 2× markup already applied"},"currency":{"type":"string","example":"USD"},"lead_time_weeks":{"$ref":"#/components/schemas/LeadTimeWeeks"},"deep_link":{"type":"string","description":"Configurator URL at selected state"}}},"ExampleConfig":{"type":"object","properties":{"mount":{"type":"string"},"fuel":{"type":"string"},"size":{"type":"string"},"finish":{"type":"string"},"retail_price":{"type":"number"},"deep_link":{"type":"string"},"note":{"type":"string"}}},"CheckoutUrlResponse":{"type":"object","required":["variant_id","cart_permalink","retail_price","currency","resolved"],"properties":{"variant_id":{"type":"string"},"variant_gid":{"type":"string"},"cart_permalink":{"type":"string","description":"Shopify URL that opens checkout with the variant pre-added"},"quantity":{"type":"integer"},"retail_price":{"type":"number"},"currency":{"type":"string"},"resolved":{"type":"object","additionalProperties":true},"deep_link":{"type":"string"},"note":{"type":"string"}}},"LeadTimeWeeks":{"type":["object","null"],"properties":{"min":{"type":"integer"},"max":{"type":"integer"},"source_text":{"type":"string","description":"Raw text from SKU shipping_availability"}}},"PriceRange":{"type":"object","required":["currency","min","max"],"properties":{"currency":{"type":"string"},"min":{"type":"number"},"max":{"type":"number"},"note":{"type":"string"}}}}},"x-configiq-platform":{"name":"ConfigIQ","url":"https://configureiq.com","contact_email":"data@configureiq.com","contract_stability":"stable within semver major 1; breaking changes announced at /.well-known/storefront.json"}}