{"openapi":"3.1.0","info":{"title":"WØWW API","version":"1.0.0","summary":"Public API of WØWW, the AI-powered Consumer Union.","description":"WØWW is the world's first AI-powered Consumer Union: members pool their collective demand and an AI negotiates better prices and terms on their existing bills.\n\nRead endpoints (`Public data`) need no key. The `Agent actions` endpoints act on a user's behalf and need an API key, sent as `Authorization: Bearer <key>`. Keys are issued per partner by WØWW; request one at hello@woww.com.\n\nSign-ups use email double opt-in: WØWW emails the user a confirmation link, and the sign-up only counts once they click it.","contact":{"name":"WØWW","email":"hello@woww.com","url":"https://woww.com"},"termsOfService":"https://woww.com/terms"},"externalDocs":{"description":"WØWW API documentation","url":"https://docs.woww.com"},"servers":[{"url":"https://api.woww.com","description":"Production"}],"tags":[{"name":"Public data","description":"Read-only facts about WØWW. No key needed."},{"name":"Agent actions","description":"Act on a user's behalf. Requires an API key."}],"paths":{"/v1/negotiate-categories":{"get":{"operationId":"listNegotiationCategories","tags":["Public data"],"summary":"List the bills WØWW negotiates","description":"Returns the categories of household bills WØWW's AI negotiates on members' behalf (mobile, internet, insurance, debt, mortgage and more), with the estimated annual savings per category in USD. Call this when a user asks how to lower their bills, what WØWW can save them, or which expenses WØWW covers.\n\nRate limit: 60 requests/minute per IP; partners that send their API key are limited per key instead.","security":[{},{"agentKey":[]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NegotiationCategories"},"example":{"ok":true,"currency":"USD","categories":[{"slug":"mobile_bills","label":"Mobile Plan","annualSavings":240},{"slug":"internet","label":"Home Internet","annualSavings":180}],"totalPotentialAnnualSavings":13010}}}},"429":{"description":"`rate_limited`: Too many requests. Wait the number of seconds in the Retry-After header.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/referral-program":{"get":{"operationId":"getReferralProgram","tags":["Public data"],"summary":"Get the referral program terms","description":"Returns the WØWW referral program terms: the reward paid per group of referred members, the group size, the maximum reward, and the rules. Call this when a user asks how referrals or referral rewards work.\n\nRate limit: 60 requests/minute per IP; partners that send their API key are limited per key instead.","security":[{},{"agentKey":[]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferralProgram"},"example":{"ok":true,"currency":"USD","rewardPerGroup":500,"groupSize":5,"maxReward":2500,"maxGroups":5,"rules":["$500 is paid for every 5 referred people who participate in the same Unlock after it becomes active. Fewer than 5 referrals do not qualify for a payout."]}}}},"429":{"description":"`rate_limited`: Too many requests. Wait the number of seconds in the Retry-After header.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/stats":{"get":{"operationId":"getMemberStats","tags":["Public data"],"summary":"Get the live member count","description":"Returns how many people have joined the WØWW Consumer Union so far. The figure is live and never cached. Call this when a user asks how big WØWW is or how many members it has.\n\nRate limit: 60 requests/minute per IP; partners that send their API key are limited per key instead.","security":[{},{"agentKey":[]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemberStats"},"example":{"ok":true,"memberCount":12345}}}},"429":{"description":"`rate_limited`: Too many requests. Wait the number of seconds in the Retry-After header.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/invite":{"post":{"operationId":"signUpUser","tags":["Agent actions"],"summary":"Sign the user up to WØWW","description":"Signs the user up to the WØWW Consumer Union so its AI can negotiate their bills. Only call this for the user you are talking to, using their own email address, after they have explicitly asked to join. WØWW then emails the user a confirmation link; the sign-up only counts once they click it, so tell the user to check their inbox. The response includes the user's personal referral link (inviteLink) — share it with them. Optionally pass the bill categories they care about and their US state.\n\nRate limit: Per API key (default 30 requests/minute).","security":[{"agentKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteRequest"},"example":{"email":"jane@example.com","usState":"CA","categories":{"mobile_bills":true,"car_insurance":true}}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteResponse"},"example":{"ok":true,"inviteLink":"https://woww.com/joinusjaneexamplecom","joinedCount":12346,"selectedSavingsTotal":940,"refAttributed":false}}}},"400":{"description":"`invalid_json`: The request body is not valid JSON. `invalid_submission`: The body failed validation (most often a malformed email address).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`agent_unauthorized`: Missing or invalid API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Too many requests. Wait the number of seconds in the Retry-After header.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`backend_not_configured`: Sign-up is temporarily unavailable. Retry later. `save_failed`: The record could not be saved. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/referral-link":{"post":{"operationId":"createReferralLink","tags":["Agent actions"],"summary":"Get the user's personal referral link","description":"Creates (or returns the existing) personal WØWW referral link for the user's email address. The link is deterministic, so calling this again for the same email returns the same link. Only call this for the user you are talking to, using their own email address, after they have explicitly asked to join. Call this when a user wants to invite friends or earn referral rewards.\n\nRate limit: Per API key (default 30 requests/minute).","security":[{"agentKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferralLinkRequest"},"example":{"email":"jane@example.com"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferralLinkResponse"},"example":{"ok":true,"inviteLink":"https://woww.com/joinusjaneexamplecom","code":"janeexamplecom"}}}},"400":{"description":"`invalid_json`: The request body is not valid JSON. `invalid_submission`: The body failed validation (most often a malformed email address).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`agent_unauthorized`: Missing or invalid API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Too many requests. Wait the number of seconds in the Retry-After header.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`backend_not_configured`: Sign-up is temporarily unavailable. Retry later. `save_failed`: The record could not be saved. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"agentKey":{"type":"http","scheme":"bearer","description":"Partner API key issued by WØWW."}},"schemas":{"Error":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"string","description":"Human-readable message."},"code":{"type":"string","description":"Machine-readable error code.","enum":["rate_limited","invalid_json","invalid_submission","agent_unauthorized","backend_not_configured","save_failed"]}}},"NegotiationCategory":{"type":"object","required":["slug","label","annualSavings"],"properties":{"slug":{"type":"string","enum":["mobile_bills","internet","car_insurance","home_insurance","insurance","credit_card_debt","mortgage","hawaii_resort_stay","alaska_cruise","auto_loan","travel","medical_costs","subscriptions","groceries"]},"label":{"type":"string"},"annualSavings":{"type":"integer","description":"Estimated annual savings for this category, in USD."}}},"NegotiationCategories":{"type":"object","required":["ok","currency","categories","totalPotentialAnnualSavings"],"properties":{"ok":{"type":"boolean","const":true},"currency":{"type":"string","const":"USD"},"categories":{"type":"array","items":{"$ref":"#/components/schemas/NegotiationCategory"}},"totalPotentialAnnualSavings":{"type":"integer","description":"Sum of the estimated annual savings across all categories, in USD."}}},"ReferralProgram":{"type":"object","required":["ok","currency","rewardPerGroup","groupSize","maxReward","maxGroups","rules"],"properties":{"ok":{"type":"boolean","const":true},"currency":{"type":"string","const":"USD"},"rewardPerGroup":{"type":"integer","description":"Reward paid per completed group of referred members."},"groupSize":{"type":"integer","description":"Number of referred members that make up one group."},"maxReward":{"type":"integer","description":"Maximum total reward per person."},"maxGroups":{"type":"integer","description":"Maximum number of rewarded groups."},"rules":{"type":"array","items":{"type":"string"}}}},"MemberStats":{"type":"object","required":["ok","memberCount"],"properties":{"ok":{"type":"boolean","const":true},"memberCount":{"type":"integer","description":"Number of people who have joined WØWW."}}},"InviteRequest":{"type":"object","required":["email"],"additionalProperties":false,"properties":{"email":{"type":"string","format":"email","maxLength":320,"description":"The user's own email address."},"usState":{"type":"string","enum":["AL","AK","AZ","AR","CA","CO","CT","DE","DC","FL","GA","HI","ID","IL","IN","IA","KS","KY","LA","ME","MD","MA","MI","MN","MS","MO","MT","NE","NV","NH","NJ","NM","NY","NC","ND","OH","OK","OR","PA","RI","SC","SD","TN","TX","UT","VT","VA","WA","WV","WI","WY"],"description":"Two-letter code of the US state the user lives in."},"categories":{"type":"object","description":"The bill categories the user wants WØWW to negotiate. Set each one they care about to true.","additionalProperties":false,"properties":{"mobile_bills":{"type":"boolean","description":"Mobile Plan"},"internet":{"type":"boolean","description":"Home Internet"},"car_insurance":{"type":"boolean","description":"Car Insurance"},"home_insurance":{"type":"boolean","description":"Home Insurance"},"insurance":{"type":"boolean","description":"Insurance"},"credit_card_debt":{"type":"boolean","description":"Credit Card Debt"},"mortgage":{"type":"boolean","description":"Mortgage"},"hawaii_resort_stay":{"type":"boolean","description":"Hawaii Resort Stay"},"alaska_cruise":{"type":"boolean","description":"Alaska Cruise"},"auto_loan":{"type":"boolean","description":"Auto Loan"},"travel":{"type":"boolean","description":"Travel"},"medical_costs":{"type":"boolean","description":"Medical Costs"},"subscriptions":{"type":"boolean","description":"Subscriptions"},"groceries":{"type":"boolean","description":"Groceries"}}},"otherComments":{"type":"string","maxLength":1000,"description":"Anything else the user wants WØWW to know."},"refCode":{"type":"string","description":"Referral code of the person who referred this user, if any (the part after /joinus in their link)."}}},"InviteResponse":{"type":"object","required":["ok","inviteLink","joinedCount","selectedSavingsTotal","refAttributed"],"properties":{"ok":{"type":"boolean","const":true},"inviteLink":{"type":"string","format":"uri","description":"The user's personal referral link. Share it with them."},"joinedCount":{"type":"integer","description":"Current member count."},"selectedSavingsTotal":{"type":"number","description":"Estimated annual savings in USD across the categories the user selected."},"refAttributed":{"type":"boolean","description":"Whether the sign-up was credited to the referrer in refCode."}}},"ReferralLinkRequest":{"type":"object","required":["email"],"additionalProperties":false,"properties":{"email":{"type":"string","format":"email","maxLength":320,"description":"The user's own email address."}}},"ReferralLinkResponse":{"type":"object","required":["ok","inviteLink","code"],"properties":{"ok":{"type":"boolean","const":true},"inviteLink":{"type":"string","format":"uri","description":"The user's personal referral link."},"code":{"type":"string","description":"The referral code inside the link."}}}}}}