{"openapi":"3.1.0","info":{"title":"HALO Homebridge Agent Commerce API","version":"2026-08-31","description":"A constrained interface for project qualification and buyer-controlled Shopify checkout handoff. The API cannot place an order or collect payment."},"servers":[{"url":"https://agent-commerce.homebridgepc.com"}],"paths":{"/v1/discovery":{"get":{"operationId":"getHomebridgeZeroInstallDiscovery","summary":"Discover HALO without installing a plugin or MCP connector","responses":{"200":{"description":"Zero-install commerce discovery contract"}}}},"/v1/catalog":{"get":{"operationId":"getHomebridgeMajorCatalog","summary":"Read all approved major-category products and live variants","responses":{"200":{"description":"Versioned live Shopify catalog projection"}}}},"/v1/catalog/{category}":{"get":{"operationId":"getHomebridgeMajorCategoryCatalog","summary":"Read one approved major-category catalog","parameters":[{"name":"category","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Category products, variants, and commerce links"},"404":{"description":"Unknown or excluded category"}}}},"/v1/configure/fire-pit":{"get":{"operationId":"qualifyOrResolveHomebridgeFirePit","summary":"Qualify a partial fire-pit request or resolve a complete selection","description":"Pass only buyer-stated choices. Missing choices return clarification guidance; four exact choices return the live Shopify variant and buyer-controlled cart link.","parameters":[{"name":"bodyStyle","in":"query","required":false,"schema":{"type":"string"}},{"name":"tabletopFinish","in":"query","required":false,"schema":{"type":"string"}},{"name":"fuelType","in":"query","required":false,"schema":{"type":"string"}},{"name":"shape","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Qualification guidance or exact live fire-pit configuration"},"400":{"description":"A supplied choice does not exactly match a supported value"}}}},"/v1/resolve":{"get":{"operationId":"resolveHomebridgeExactMajorVariant","summary":"Resolve one buyer-confirmed exact Shopify variant","description":"Use category, productHandle, and option.<Shopify option name>=<exact value> query parameters. Returns the variant image, price, availability, exact product URL, and buyer-controlled cart URL.","parameters":[{"name":"category","in":"query","required":true,"schema":{"type":"string"}},{"name":"productHandle","in":"query","required":true,"schema":{"type":"string"}},{"name":"option.<name>","in":"query","required":true,"schema":{"type":"string"}},{"name":"source","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Exact live Shopify variant with commerce links"},"400":{"description":"Missing or invalid exact selection"},"404":{"description":"No exact approved variant matches"}}}},"/v1/videos":{"get":{"operationId":"getHomebridgeCuratedVideos","summary":"Read approved brand- and category-level Homebridge videos","description":"Videos are associated with the brand or category and must not be described as footage of an exact selected SKU.","parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Curated public YouTube video map"}}}},"/discover/{category}/{sku}":{"get":{"operationId":"getHomebridgeExactVariantPage","summary":"Read a crawlable exact-variant product and commerce page","description":"Returns HTML with the exact selected Shopify variant, Product and Offer JSON-LD, variant-associated image, current price, disclosures, product URL, and eligible buyer-controlled cart link.","parameters":[{"name":"category","in":"path","required":true,"schema":{"type":"string"}},{"name":"sku","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Crawlable exact Shopify variant page"},"404":{"description":"Unknown category or exact SKU"}}}},"/v1/agent/offers":{"get":{"operationId":"listHomebridgeCategoriesAndOffers","summary":"List qualification categories and currently enabled exact offers","responses":{"200":{"description":"Category roadmap and enabled offers"}}}},"/v1/agent/offers/{sku}":{"get":{"operationId":"getApprovedHomebridgeOffer","summary":"Read one enabled exact offer","security":[{"agentBearer":[]}],"parameters":[{"name":"sku","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Approved exact offer"},"401":{"description":"Missing, invalid, revoked, or expired credential"},"403":{"description":"Credential lacks scope or offer permission"},"410":{"description":"Offer is not enabled"}}}},"/v1/agent/checkout-sessions":{"post":{"operationId":"createHomebridgeBuyerCheckout","summary":"Create a Shopify-hosted checkout for buyer review","description":"The client cannot submit a price, discount, variant ID, shipping promise, or total. The buyer must review and complete Shopify Checkout.","security":[{"agentBearer":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":16}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSessionRequest"}}}},"responses":{"201":{"description":"Shopify checkout ready for buyer review"},"401":{"description":"Missing, invalid, revoked, or expired credential"},"403":{"description":"Credential lacks scope or offer permission"},"503":{"description":"Global agent-commerce kill switch is engaged"}}}}},"components":{"securitySchemes":{"agentBearer":{"type":"http","scheme":"bearer","bearerFormat":"HALO agent credential"}},"schemas":{"CheckoutSessionRequest":{"type":"object","additionalProperties":false,"required":["sku","quantity","source","buyerAcknowledgements"],"properties":{"sku":{"type":"string","maxLength":100},"quantity":{"type":"integer","minimum":1},"source":{"type":"string","maxLength":80},"agentSessionId":{"type":"string","maxLength":200},"buyerAcknowledgements":{"type":"object","additionalProperties":{"const":true}}}}}}}