{"openapi":"3.1.0","info":{"title":"Factorz buying advisor","description":"Live product decision engine: real inventory, specs, prices and fit scores per user profile.","version":"gpt-actions-v1"},"servers":[{"url":"https://gpt-actions.factorz.io"}],"components":{"schemas":{"Profile":{"type":"object","description":"Structured buying profile built during the conversation.","properties":{"category":{"type":"string","description":"Product category, as the user named it"},"answers":{"type":"array","description":"Every factor covered, including inferred ones","items":{"type":"object","properties":{"question":{"type":"string"},"answer":{"type":"string"},"inferred":{"type":"boolean","description":"true if deduced, not asked directly"}},"required":["question","answer"]}},"budget":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}}},"mustHaves":{"type":"array","items":{"type":"string"}},"niceToHaves":{"type":"array","items":{"type":"string"}},"avoid":{"type":"array","items":{"type":"string"}},"summary":{"type":"string","description":"2-3 sentence portrait of this buyer"}},"required":["category","answers"]}}},"paths":{"/session":{"post":{"operationId":"startSession","x-openai-isConsequential":false,"summary":"REQUIRED first call of every conversation","description":"MUST be called before you answer the user's first message in any product conversation - always, no exception. Returns sessionId, the instructions for stage 1 (you do not have them otherwise), the real factor sheet for this category, and the user's previous sessions.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string","description":"Category the user wants, e.g. 'טלוויזיה' or 'robot vacuum'"}},"required":["category"]}}}},"responses":{"200":{"description":"Session created"}}}},"/stage":{"post":{"operationId":"getStage","x-openai-isConsequential":false,"summary":"REQUIRED before entering stage 2 or 3","description":"Returns the instructions for that stage of the advisory process - what to do, the exact output formats, and when to move on. You do not have these instructions otherwise. Call with stage=2 after the profile is presented, and stage=3 before diving into prices.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"},"stage":{"type":"number","description":"1, 2 or 3"}},"required":["sessionId","stage"]}}}},"responses":{"200":{"description":"Stage playbook"}}}},"/query":{"post":{"operationId":"queryProducts","x-openai-isConsequential":false,"summary":"Rank real products against the current answer set","description":"Supported categories only. Send the FULL current answer set every call (omitted answers are cleared). choice factors take answerId; importance factors take weight 0-3. Response includes ranked products with fit scores and a coach block saying whether enough is covered to recommend.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"},"answers":{"type":"array","items":{"type":"object","properties":{"questionId":{"type":"number"},"answerId":{"type":"number"},"weight":{"type":"number","description":"0-3, importance factors only"}},"required":["questionId"]}},"filters":{"type":"array","items":{"type":"object","properties":{"field":{"type":"number"},"value":{"type":"string"}},"required":["field","value"]}},"pageSize":{"type":"number"}},"required":["sessionId","answers"]}}}},"responses":{"200":{"description":"Ranked products + coach"}}}},"/profile":{"post":{"operationId":"saveProfile","x-openai-isConsequential":false,"summary":"Save the finished buying profile","description":"Call once the questioning phase is complete (every category, including unsupported ones), and again if the profile materially changes. This is what lets the user continue in a future conversation.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"},"profile":{"$ref":"#/components/schemas/Profile"}},"required":["sessionId","profile"]}}}},"responses":{"200":{"description":"Saved"}}}},"/profile/{sessionId}":{"get":{"operationId":"getProfile","x-openai-isConsequential":false,"summary":"Fetch a previously saved profile","description":"Use when the user wants to continue a previous session (startSession lists them). Returns the saved profile to resume from — re-ask only what might have changed.","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The saved profile"}}}},"/links":{"post":{"operationId":"createLinks","x-openai-isConsequential":false,"summary":"REQUIRED to produce any purchase link","description":"Turn the stores and prices you found into purchase links. You must never write a store URL yourself: send product, store, url and price, and use the returned URLs exactly as given. They carry the tracking and affiliate parameters, which a URL you build would lose.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"},"products":{"type":"array","items":{"type":"object","properties":{"product":{"type":"string"},"store":{"type":"string"},"url":{"type":"string","description":"the store URL exactly as you found it"},"price":{"type":"number"}},"required":["product","store","url"]}}},"required":["sessionId","products"]}}}},"responses":{"200":{"description":"Ready-to-paste links"}}}},"/event":{"post":{"operationId":"logEvent","x-openai-isConsequential":false,"summary":"Report a conversation milestone","description":"Fire-and-forget analytics. Call with type 'recommended' when you present final picks (data.products = names), 'buy_link_shown' when you give purchase links, 'user_dropped' if the user clearly abandons.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"},"type":{"type":"string"},"data":{"type":"object"}},"required":["sessionId","type"]}}}},"responses":{"200":{"description":"Logged"}}}},"/product/{productId}":{"get":{"operationId":"productDetails","x-openai-isConsequential":false,"summary":"Full details for one product","description":"Supported categories only: specs, pros/cons and vendor offers for a product returned by queryProducts.","parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"number"}},{"name":"sessionId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Product detail"}}}}}}