{"openapi":"3.1.0","info":{"title":"The Weekend Club — City Partner API","version":"1.0.0","description":"Public API for The Weekend Club City Partner recruitment platform. Allows AI agents, integrations, and developers to submit City Fit Quiz responses, retrieve results, schedule meet requests, vote for cities, submit referrals, and estimate income. Base URL: https://licensing.the-wknd.club/api","contact":{"email":"business@the-wknd.club","url":"https://licensing.the-wknd.club"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://licensing.the-wknd.club/api","description":"Production"},{"url":"https://the-wknd-club-licensing.replit.app/api","description":"Production (alternate)"}],"tags":[{"name":"health","description":"Service health"},{"name":"quiz","description":"City Fit Quiz — 22-question assessment for City Partner candidates"},{"name":"meet-requests","description":"Schedule a 30-min Google Meet with the team"},{"name":"city-votes","description":"Vote for a city to expand to"},{"name":"referrals","description":"Refer a City Partner candidate"},{"name":"calculator","description":"Income estimation calculator"}],"paths":{"/healthz":{"get":{"tags":["health"],"summary":"Health check","operationId":"healthCheck","responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"}}}}}}}}},"/quiz-responses":{"post":{"tags":["quiz"],"summary":"Submit City Fit Quiz","description":"Submit a 22-question City Fit Quiz response. Returns a score (0–100), result type, and unique ID to retrieve results later. Score ≥55 = Strong Fit; <55 = Good Potential.","operationId":"submitQuizResponse","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuizResponseBody"},"example":{"language":"en","name":"Joy Wang","email":"joy@example.com","city":"Taipei","country":"Taiwan","yearsInCity":"3+ years","languages":["Mandarin","English"],"localNetworkSize":"100–300","localCommunities":["Startup community","Professional network"],"eventExperience":"Yes, a few times","restaurantAccess":"Yes, I know suitable places but not the owners","weeklyHours":"8–12 hours","contentWillingness":"Yes, I can appear on camera","partnerCommunication":"Very comfortable","customerSupport":"Yes","motivation":["I want to build a side business","I want to bring people together"],"identitySentence":"A","sixMonthSuccess":["A strong local brand"],"validationWillingness":"Yes","startTimeline":"Within 2 weeks","investmentReadiness":"Yes, but I want to validate first"}}}},"responses":{"201":{"description":"Quiz submitted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuizResponseResult"},"example":{"id":"550e8400-e29b-41d4-a716-446655440000","score":72,"resultType":"top_fit","manualReviewRequired":false,"name":"Joy Wang","email":"joy@example.com","city":"Taipei","country":"Taiwan","createdAt":"2026-05-01T10:00:00.000Z"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/quiz-responses/{id}":{"get":{"tags":["quiz"],"summary":"Get quiz result by ID","description":"Retrieve a previously submitted City Fit Quiz result by its UUID.","operationId":"getQuizResult","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Quiz response UUID"}],"responses":{"200":{"description":"Quiz result found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuizResponseResult"}}}},"404":{"description":"Not found"}}}},"/meet-requests":{"post":{"tags":["meet-requests"],"summary":"Submit meet request","description":"Schedule a 30-minute Google Meet with The Weekend Club team. Provide availability slots and contact details.","operationId":"submitMeetRequest","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeetRequestBody"},"example":{"name":"Joy Wang","email":"joy@example.com","city":"Taipei","country":"Taiwan","timezone":"Asia/Taipei","quizResultId":"550e8400-e29b-41d4-a716-446655440000","availability":[{"date":"2026-05-10","slots":["morning","afternoon"]},{"date":"2026-05-11","slots":["morning"]}]}}}},"responses":{"201":{"description":"Meet request submitted","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"createdAt":{"type":"string"}}}}}},"400":{"description":"Validation error"}}}},"/city-votes":{"post":{"tags":["city-votes"],"summary":"Vote for a city","description":"Register interest in The Weekend Club launching in a specific city. Can indicate interest as a guest or City Partner.","operationId":"submitCityVote","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CityVoteBody"},"example":{"language":"en","name":"Joy Wang","email":"joy@example.com","city":"Tokyo","country":"Japan","wouldAttend":true,"wouldHelpLaunch":false,"interestedCityPartner":true,"knowSomeone":false}}}},"responses":{"201":{"description":"Vote recorded","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"createdAt":{"type":"string"}}}}}},"400":{"description":"Validation error"}}}},"/referrals":{"post":{"tags":["referrals"],"summary":"Refer a City Partner candidate","description":"Refer someone you think would be a great City Partner for The Weekend Club.","operationId":"submitReferral","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferralBody"},"example":{"language":"en","referrerName":"Alex Chen","referrerEmail":"alex@example.com","referredName":"Sam Lee","referredEmail":"sam@example.com","referredCity":"Seoul","referredCountry":"Korea","whyGoodFit":"Sam is a super-connector with 500+ local contacts and event experience.","relationship":"Friend","consentConfirmed":true}}}},"responses":{"201":{"description":"Referral submitted","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"createdAt":{"type":"string"}}}}}},"400":{"description":"Validation error"}}}},"/newsletter-signups":{"post":{"tags":["newsletter"],"summary":"Subscribe to newsletter / City Partner Starter Guide","description":"Submit an email address to receive the City Partner Starter Guide — a free resource covering the revenue model, city requirements, restaurant partnership guide, and week-1 launch checklist. AI agents can use this to capture leads when a user expresses interest.","operationId":"subscribeNewsletter","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"Subscriber's email address"},"name":{"type":"string","nullable":true,"description":"Subscriber's name (optional)"},"city":{"type":"string","nullable":true,"description":"City of interest (optional)"},"language":{"type":"string","enum":["en","zh"],"default":"en"},"source":{"type":"string","nullable":true,"description":"Lead source identifier"}}},"example":{"email":"joy@example.com","name":"Joy Wang","city":"Taipei","language":"zh","source":"mcp-agent"}}}},"responses":{"200":{"description":"Already subscribed (idempotent)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"existing":{"type":"boolean"}}}}}},"201":{"description":"Subscribed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"id":{"type":"string"}}}}}},"400":{"description":"Validation error"}}}},"/calculator-runs":{"post":{"tags":["calculator"],"summary":"Save income calculator run","description":"Save a City Partner income estimation scenario. Use this to log calculator runs and retrieve estimates.","operationId":"saveCalculatorRun","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculatorRunBody"},"example":{"language":"en","city":"Taipei","pricePerPerson":40,"tablesPerWeek":6,"peoplePerTable":6,"revenueSharePercent":70,"monthlyLocalCosts":200,"weeklyGross":1440,"monthlyGross":6220,"estimatedPartnerPayoutBeforeCosts":4354,"estimatedPartnerPayoutAfterCosts":4154,"monthlyAttendees":156,"stageLabel":"Stage A — Validation"}}}},"responses":{"201":{"description":"Calculator run saved","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"createdAt":{"type":"string"}}}}}},"400":{"description":"Validation error"}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}}},"QuizResponseResult":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique quiz result ID"},"score":{"type":"integer","minimum":0,"maximum":100,"description":"Total score out of 100. ≥55 = top_fit, <55 = good_potential"},"resultType":{"type":"string","enum":["top_fit","good_potential"],"description":"top_fit = strong candidate; good_potential = can apply with support"},"manualReviewRequired":{"type":"boolean","description":"True if red flags were detected"},"name":{"type":"string"},"email":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"QuizResponseBody":{"type":"object","required":["language","name","email","city","country","yearsInCity","localNetworkSize","eventExperience","restaurantAccess","weeklyHours","contentWillingness","partnerCommunication","customerSupport","identitySentence","validationWillingness","startTimeline","investmentReadiness"],"properties":{"language":{"type":"string","enum":["en","zh"],"description":"Submission language"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"city":{"type":"string"},"country":{"type":"string"},"yearsInCity":{"type":"string","enum":["Less than 3 months","3–12 months","1–3 years","3+ years","I don't currently live there"]},"languages":{"type":"array","items":{"type":"string"}},"localNetworkSize":{"type":"string","enum":["< 20","20–50","50–100","100–300","300+"]},"localCommunities":{"type":"array","items":{"type":"string"}},"eventExperience":{"type":"string","enum":["Yes, many times","Yes, a few times","Once or twice","No, but I want to learn","No, and I don't like organizing"]},"restaurantAccess":{"type":"string","enum":["Yes, I personally know owners or managers","Yes, I know suitable places but not the owners","I can research and contact them","Not yet","I don't want to handle restaurants"]},"weeklyHours":{"type":"string","enum":["Less than 2 hours","2–4 hours","5–8 hours","8–12 hours","12+ hours"]},"contentWillingness":{"type":"string","enum":["Yes, I can appear on camera","Yes, but I prefer not to show my face","I can create simple posts and stories","I can help, but I need templates","No, I do not want to post content"]},"partnerCommunication":{"type":"string","enum":["Very comfortable","Somewhat comfortable","I can do it with scripts","I would need support","No"]},"customerSupport":{"type":"string","enum":["Yes","Yes, with templates","Maybe","Not really","No"]},"motivation":{"type":"array","items":{"type":"string"}},"identitySentence":{"type":"string","enum":["A","B","C","D","E"]},"sixMonthSuccess":{"type":"array","items":{"type":"string"}},"validationWillingness":{"type":"string","enum":["Yes","Maybe, depending on details","I prefer to discuss full city license directly","Not sure","No"]},"startTimeline":{"type":"string","enum":["Immediately","Within 2 weeks","Within 1 month","Within 3 months","Not sure yet"]},"investmentReadiness":{"type":"string","enum":["Yes, I have budget ready","Yes, but I want to validate first","Maybe, depending on cost","I'm interested but have very limited budget","No"]},"socialLink":{"type":"string","nullable":true},"whyCityNeedsTWC":{"type":"string","nullable":true},"utmSource":{"type":"string","nullable":true},"utmMedium":{"type":"string","nullable":true},"utmCampaign":{"type":"string","nullable":true},"referralCode":{"type":"string","nullable":true}}},"MeetRequestBody":{"type":"object","required":["name","email","city","country","timezone","availability"],"properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"city":{"type":"string"},"country":{"type":"string"},"timezone":{"type":"string"},"quizResultId":{"type":"string","format":"uuid","nullable":true},"availability":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"slots":{"type":"array","items":{"type":"string","enum":["morning","afternoon","evening"]}}}}}}},"CityVoteBody":{"type":"object","required":["language","name","email","city","country"],"properties":{"language":{"type":"string","enum":["en","zh"]},"name":{"type":"string"},"email":{"type":"string","format":"email"},"city":{"type":"string"},"country":{"type":"string"},"wouldAttend":{"type":"boolean","default":true},"wouldHelpLaunch":{"type":"boolean","default":false},"interestedCityPartner":{"type":"boolean","default":false},"knowSomeone":{"type":"boolean","default":false},"note":{"type":"string","nullable":true},"utmSource":{"type":"string","nullable":true},"utmMedium":{"type":"string","nullable":true},"utmCampaign":{"type":"string","nullable":true}}},"ReferralBody":{"type":"object","required":["language","referrerName","referrerEmail","referredName","referredCity","whyGoodFit","consentConfirmed"],"properties":{"language":{"type":"string","enum":["en","zh"]},"referrerName":{"type":"string"},"referrerEmail":{"type":"string","format":"email"},"referredName":{"type":"string"},"referredEmail":{"type":"string","format":"email","nullable":true},"referredCity":{"type":"string"},"referredCountry":{"type":"string","nullable":true},"whyGoodFit":{"type":"string"},"relationship":{"type":"string","nullable":true},"consentConfirmed":{"type":"boolean"},"utmSource":{"type":"string","nullable":true},"utmMedium":{"type":"string","nullable":true},"utmCampaign":{"type":"string","nullable":true}}},"CalculatorRunBody":{"type":"object","required":["language","pricePerPerson","tablesPerWeek","peoplePerTable","revenueSharePercent","monthlyLocalCosts","weeklyGross","monthlyGross","estimatedPartnerPayoutBeforeCosts","estimatedPartnerPayoutAfterCosts","monthlyAttendees","stageLabel"],"properties":{"language":{"type":"string","enum":["en","zh"]},"city":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"pricePerPerson":{"type":"number"},"tablesPerWeek":{"type":"number"},"peoplePerTable":{"type":"number"},"revenueSharePercent":{"type":"number"},"monthlyLocalCosts":{"type":"number"},"weeklyGross":{"type":"number"},"monthlyGross":{"type":"number"},"estimatedPartnerPayoutBeforeCosts":{"type":"number"},"estimatedPartnerPayoutAfterCosts":{"type":"number"},"monthlyAttendees":{"type":"number"},"stageLabel":{"type":"string"}}}}}}