{"openapi":"3.1.0","info":{"title":"ktown Public API","version":"1.0.0","description":"Read-only discovery API for ktown group-buy listings (Vancouver-first, CAD). Purchasing is via the ktown website. Also see MCP at /api/mcp, Server Card at /api/mcp/server-card, AI Catalog at /.well-known/ai-catalog.json, llms.txt, and catalog-feed.csv.","contact":{"name":"ktown","url":"https://ktown.io"}},"externalDocs":{"description":"Agent discovery index (llms.txt)","url":"https://ktown.io/llms.txt"},"servers":[{"url":"https://ktown.io/api/v1/public"}],"paths":{"/listings":{"get":{"operationId":"listListings","summary":"Search and list public group-buy listings","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"city","in":"query","schema":{"type":"string"},"description":"Market slug from public.cities (e.g. vancouver). Defaults to enabled cities."},{"name":"region","in":"query","schema":{"type":"string"},"description":"Free-text match on listing city/province within enabled markets"},{"name":"province","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"closing_soon","in":"query","schema":{"type":"boolean"}},{"name":"fulfillment","in":"query","schema":{"type":"string","enum":["pickup","local_delivery","shipping"]}},{"name":"price_min_minor","in":"query","schema":{"type":"integer"}},{"name":"price_max_minor","in":"query","schema":{"type":"integer"}},{"name":"commerce_mode","in":"query","schema":{"type":"string","enum":["group_buy","standard"]}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":50}}],"responses":{"200":{"description":"Paginated listing summaries"},"429":{"description":"Rate limited"}}}},"/listings/{id}":{"get":{"operationId":"getListing","summary":"Get one listing with group-buy progress and fulfillment options","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Listing detail"},"404":{"description":"Not found or not public"}}}},"/sellers":{"get":{"operationId":"listSellers","summary":"List sellers with public storefront handles","parameters":[{"name":"region","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":50}}],"responses":{"200":{"description":"Seller summaries"}}}},"/sellers/{handle}":{"get":{"operationId":"getSellerStorefront","summary":"Seller storefront with active listings","parameters":[{"name":"handle","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Storefront payload"},"404":{"description":"Unknown handle"}}}},"/schema-gaps":{"get":{"operationId":"getSchemaGaps","summary":"Known fields that return null until DB migrations land","responses":{"200":{"description":"Gap list"}}}},"/catalog-feed.csv":{"get":{"operationId":"getStripeCatalogFeed","summary":"Stripe Agentic Commerce product catalog (CSV, discovery-only)","description":"Full-catalog CSV snapshot for Stripe Agentic Commerce / compatible agents. Every row sets disable_checkout=true so purchases redirect to ktown join URLs.","responses":{"200":{"description":"text/csv feed"},"429":{"description":"Rate limited"}}}}},"x-schema-gaps":[{"id":"region_areas","field":"region_area slug / FSA prefixes","note":"Markets use public.cities (city slug on API region.region_slug); sub-areas (Burnaby, North York) not modeled yet."},{"id":"title_ko","field":"title_ko, description_ko","note":"Bilingual listing columns not in listing table; EN fields only."},{"id":"group_buys_entity","field":"group_buy.round_id, tipped_at","note":"Campaign window lives on listing row; no separate group_buys table."},{"id":"min_units_wizard","field":"group_buy.min_units","note":"Uses listing.min_quantity when column exists; may be unset on legacy rows."},{"id":"fulfillment_options","field":"fulfillment[] multiple pickup points","note":"Single pickup/delivery/shipping columns on listing until M3 fulfillment_options."},{"id":"public_listings_view","field":"public_listings_v, catalog_feed_exports audit table","note":"MCP + CSV feed use listing serializers today; SQL view + export audit rows land in M10."}]}