{"openapi":"3.1.0","info":{"title":"Carver Public API","version":"1.0.0","description":"Search Hong Kong consumer pain points, generate research briefs, and ask the AI business consultant. Read endpoints return a public, freshness-lagged, safe-column surface. AI endpoints require a Pro-tier key and count against a monthly quota. See https://carverhk.com/developers.","contact":{"name":"Carver","url":"https://carverhk.com/developers","email":"hello@carverhk.com"}},"servers":[{"url":"https://carverhk.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key (if_live_…). Mint one at Account → API Access (Pro)."}},"schemas":{"PainPointSummary":{"type":"object","properties":{"slug":{"type":"string"},"headline":{"type":"string"},"domain":{"type":"string","nullable":true},"composite_score":{"type":"number","nullable":true},"pain_severity":{"type":"number","nullable":true},"frequency":{"type":"number","nullable":true},"unmet_need_score":{"type":"number","nullable":true},"reply_count":{"type":"integer"},"first_seen_month":{"type":"string","nullable":true}}}}},"paths":{"/api/v1/painpoints":{"get":{"summary":"Search / list pain points","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Free-text search."},{"name":"domain","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0}},{"name":"sort","in":"query","schema":{"type":"string","enum":["score","discussed","newest","oldest"]}},{"name":"period","in":"query","schema":{"type":"string","enum":["latest","3m","6m"]}}],"responses":{"200":{"description":"Matching pain points","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/PainPointSummary"}}}}}}},"401":{"description":"Missing or invalid API key"}}}},"/api/v1/painpoints/{slug}":{"get":{"summary":"Get a single pain point","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Pain point detail"},"404":{"description":"Not found"}}}},"/api/v1/research-brief":{"post":{"summary":"Generate a research brief (Pro)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slug"],"properties":{"slug":{"type":"string"},"locale":{"type":"string","enum":["zh-Hant","en"]},"input":{"type":"object","properties":{"user_context":{"type":"string"},"budget_tier":{"type":"string","enum":["ai_hustle","bootstrap","lean","funded","custom"]},"budget_custom":{"type":"number"},"timeline_months":{"type":"integer"},"role_shape":{"type":"string","enum":["solo","duo","team"]}}}}}}}},"responses":{"200":{"description":"Brief sections"},"403":{"description":"Pro required or quota exceeded"}}}},"/api/v1/consultant":{"post":{"summary":"Ask the AI business consultant (Pro)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string"},"locale":{"type":"string","enum":["zh-Hant","en"]}}}}}},"responses":{"200":{"description":"Consultant reply"},"403":{"description":"Pro required"},"429":{"description":"Monthly chat quota exceeded"}}}}}}