{"openapi":"3.1.0","info":{"title":"San Collective Marketplace API","version":"2026-06-21","description":"Shopify-first marketplace API for product discovery, comparison, and checkout handoff. San Collective is never the merchant of record and does not scrape merchant storefronts."},"servers":[{"url":"https://sancollective.com"}],"paths":{"/api/assistant":{"post":{"operationId":"assistantSearch","summary":"Rewrite a natural-language shopping request into a query and filters.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string"},"includeResults":{"type":"boolean","description":"When true, response includes a filtered SearchResponse."},"shipsToCountry":{"type":"string","description":"ISO-3166 alpha-2."},"priceCurrency":{"type":"string","description":"ISO-4217."},"limit":{"type":"integer","minimum":1,"maximum":100}}}}}},"responses":{"200":{"description":"Assistant query rewrite with filters and optional filtered search results."}}}},"/api/search":{"post":{"operationId":"searchCatalog","summary":"Search the Shopify Catalog.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string"},"shipsToCountry":{"type":"string","description":"ISO-3166 alpha-2."},"region":{"type":"string"},"priceCurrency":{"type":"string","description":"ISO-4217."},"priceMax":{"type":"number","description":"Maximum product/offer price."},"availableNow":{"type":"boolean","description":"Only include products with in-stock or limited offers."},"seller":{"type":"string","description":"Filter by seller name, id, or URL."},"limit":{"type":"integer","minimum":1,"maximum":100},"cursor":{"type":"string"}}}}}},"responses":{"200":{"$ref":"#/components/responses/SearchResponse"}}}},"/api/product":{"get":{"operationId":"getProduct","summary":"Full product detail by id.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}},{"name":"shipsToCountry","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Product detail with offers and checkout URLs."}}}},"/api/compare":{"post":{"operationId":"compareProduct","summary":"Find comparable products across merchants.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["productId","title"],"properties":{"productId":{"type":"string"},"title":{"type":"string"},"sellerName":{"type":"string"},"shipsToCountry":{"type":"string"}}}}}},"responses":{"200":{"description":"Ranked comparable products."}}}},"/api/compare-summary":{"post":{"operationId":"compareSummary","summary":"Generate a grounded comparison summary for selected products.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["products"],"properties":{"products":{"type":"array","items":{"type":"object","required":["title"],"properties":{"title":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"},"availability":{"type":"string"},"seller":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"Short comparison summary grounded in provided product data."}}}},"/api/cart":{"post":{"operationId":"groupCart","summary":"Group collected items into one Shopify checkout per merchant.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"type":"object","required":["productId"],"properties":{"productId":{"type":"string"},"variantId":{"type":"string"},"quantity":{"type":"integer","minimum":1,"maximum":99},"checkoutUrl":{"type":"string"},"seller":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"}}}}}},"checkoutStrategy":{"type":"string","enum":["permalink","ucp_cart"],"description":"Use ucp_cart to try merchant UCP Cart MCP first; falls back to Shopify checkout URLs/cart permalinks."},"shipsToCountry":{"type":"string"},"region":{"type":"string"},"postalCode":{"type":"string"}}}}}},"responses":{"200":{"description":"Merchant-grouped checkout options. One checkout group per Shopify store, with UCP cart metadata when requested and a checkout URL fallback where possible."}}}},"/api/checkout-handoff":{"post":{"operationId":"checkoutHandoff","summary":"Resolve a single-item Shopify checkout URL.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["productId"],"properties":{"productId":{"type":"string"},"variantId":{"type":"string"},"quantity":{"type":"integer","minimum":1,"maximum":99},"checkoutUrl":{"type":"string"},"shipsToCountry":{"type":"string"}}}}}},"responses":{"200":{"description":"Checkout handoff with resolved checkoutUrl."}}}},"/api/lookup":{"post":{"operationId":"lookupCatalog","summary":"Batch product lookup by id or url.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}},"urls":{"type":"array","items":{"type":"string"}},"shipsToCountry":{"type":"string"}}}}}},"responses":{"200":{"description":"Looked-up products."}}}},"/api/capabilities":{"get":{"operationId":"getCapabilities","summary":"Machine-readable capability + policy document.","responses":{"200":{"description":"Capabilities document."}}}}},"components":{"responses":{"SearchResponse":{"description":"Search results with pagination and attribution.","content":{"application/json":{"schema":{"type":"object"}}}}}}}