{"openapi":"3.1.0","info":{"title":"CommunityHunt API","version":"1.0.0","description":"CommunityHunt is a directory for discovering and submitting online and offline communities — for builders, designers, marketers, gamers, and everyone in between.\n\nRead endpoints require no authentication. Write endpoints require a signed-in CommunityHunt session (browser cookie via Clerk) — there is currently no separate API key system for writes.","contact":{"email":"hello@communityhunt.in","url":"https://communityhunt.in/developers"}},"servers":[{"url":"https://communityhunt.in"}],"tags":[{"name":"Communities","description":"Browse and manage community listings"},{"name":"Events","description":"Browse and manage events hosted by listed communities"}],"paths":{"/api/communities":{"get":{"tags":["Communities"],"summary":"Search and list communities","description":"Public, unauthenticated. Returns approved communities only, paginated.","operationId":"listCommunities","parameters":[{"name":"search","in":"query","schema":{"type":"string"},"description":"Free-text search across name, tagline, description, and target audience"},{"name":"category","in":"query","schema":{"type":"string","enum":["Tech","AI","Design","Marketing","Startup","Product","Gaming","Web3","Finance","Health","Education","Career","Lifestyle","Open Source"]}},{"name":"pricing","in":"query","schema":{"type":"string","enum":["Free","Freemium","Paid"]}},{"name":"mode","in":"query","schema":{"type":"string","enum":["Online","Offline","Hybrid"]}},{"name":"location","in":"query","schema":{"type":"string"},"description":"\"city,country\" or just a city"},{"name":"language","in":"query","schema":{"type":"string"}},{"name":"memberSize","in":"query","schema":{"type":"string","enum":["lt100","100-1k","1k-10k","gt10k"]}},{"name":"hasEvent","in":"query","schema":{"type":"boolean"},"description":"Only communities with an approved upcoming event"},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}}],"responses":{"200":{"description":"A page of communities","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Community"}},"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"totalPages":{"type":"integer"},"filterOptions":{"type":"object","properties":{"locations":{"type":"array","items":{"type":"string"}},"languages":{"type":"array","items":{"type":"string"}}}}}}}}}}},"post":{"tags":["Communities"],"summary":"Submit a new community","description":"Requires a signed-in session. New submissions are created with status \"pending\" and reviewed before appearing publicly.","operationId":"submitCommunity","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"logo":{"type":"string","description":"data: URI of a JPG/PNG, base64-encoded"},"tagline":{"type":"string"},"description":{"type":"string"},"targetAudience":{"type":"string"},"categories":{"type":"array","items":{"type":"string","enum":["Tech","AI","Design","Marketing","Startup","Product","Gaming","Web3","Finance","Health","Education","Career","Lifestyle","Open Source"]}},"pricing":{"type":"string","enum":["Free","Freemium","Paid"]},"mode":{"type":"string","enum":["Online","Offline","Hybrid"]},"location":{"type":"object","properties":{"city":{"type":"string"},"country":{"type":"string"}}},"language":{"type":"string"},"memberCount":{"type":"integer"},"links":{"type":"object"},"host":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]},"contact":{"type":"object"},"upcomingEvent":{"type":"object","nullable":true}},"required":["name","tagline","description","targetAudience","categories","pricing","mode","host"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/communities/{id}":{"get":{"tags":["Communities"],"summary":"Get a community by id","description":"Public, unauthenticated. Only returns approved communities.","operationId":"getCommunity","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The community","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Community"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Communities"],"summary":"Update a community you own","operationId":"updateCommunity","security":[{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Partial community fields"}}}},"responses":{"200":{"description":"Updated community","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Community"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden (not the owner)"},"404":{"description":"Not found"}}},"delete":{"tags":["Communities"],"summary":"Delete a community you own","operationId":"deleteCommunity","security":[{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"}}}},"/api/communities/{id}/claim":{"post":{"tags":["Communities"],"summary":"Request to claim an unclaimed community","operationId":"claimCommunity","security":[{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"responses":{"201":{"description":"Claim request created"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"},"409":{"description":"Already claimed or a pending request already exists"}}}},"/api/communities/{id}/events":{"post":{"tags":["Events"],"summary":"Create an event for a community you own","operationId":"createEvent","security":[{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Community id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"date":{"type":"string","format":"date-time"},"location":{"type":"string"},"link":{"type":"string","format":"uri"}},"required":["title","date"]}}}},"responses":{"201":{"description":"Created event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden (not the owner)"}}}},"/api/events":{"get":{"tags":["Events"],"summary":"List upcoming events","description":"Public, unauthenticated. Only approved events from approved communities, paginated.","operationId":"listEvents","parameters":[{"name":"search","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}}],"responses":{"200":{"description":"A page of events","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"totalPages":{"type":"integer"}}}}}}}}},"/api/events/{id}":{"patch":{"tags":["Events"],"summary":"Update an event you own","operationId":"updateEvent","security":[{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Partial event fields"}}}},"responses":{"200":{"description":"Updated event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}}},"delete":{"tags":["Events"],"summary":"Delete an event you own","operationId":"deleteEvent","security":[{"cookieAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}}}}},"components":{"securitySchemes":{"cookieAuth":{"type":"apiKey","in":"cookie","name":"__session","description":"Clerk session cookie set after signing in at https://communityhunt.in/sign-in. There is no separate API key for write operations."}},"schemas":{"Community":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["approved","pending","rejected"]},"ownerId":{"type":"string","nullable":true,"description":"Null when the listing is unclaimed"},"name":{"type":"string"},"logo":{"type":"string","nullable":true},"tagline":{"type":"string"},"description":{"type":"string"},"targetAudience":{"type":"string"},"categories":{"type":"array","items":{"type":"string","enum":["Tech","AI","Design","Marketing","Startup","Product","Gaming","Web3","Finance","Health","Education","Career","Lifestyle","Open Source"]}},"pricing":{"type":"string","enum":["Free","Freemium","Paid"]},"mode":{"type":"string","enum":["Online","Offline","Hybrid"]},"location":{"type":"object","nullable":true,"properties":{"city":{"type":"string"},"country":{"type":"string"}}},"language":{"type":"string","nullable":true},"memberCount":{"type":"integer","nullable":true},"links":{"type":"object","nullable":true,"properties":{"website":{"type":"string","format":"uri"},"twitter":{"type":"string","format":"uri"},"linkedin":{"type":"string","format":"uri"},"discord":{"type":"string","format":"uri"},"slack":{"type":"string","format":"uri"},"instagram":{"type":"string","format":"uri"},"github":{"type":"string","format":"uri"}}},"host":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":"string"},"bio":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"},"link":{"type":"string","format":"uri"}},"required":["name"]},"contact":{"type":"object","nullable":true,"properties":{"email":{"type":"string","format":"email"},"twitter":{"type":"string"}}},"featured":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"events":{"type":"array","items":{"$ref":"#/components/schemas/Event"}}},"required":["id","slug","status","name","tagline","description","targetAudience","categories","pricing","mode","host","createdAt"]},"Event":{"type":"object","properties":{"id":{"type":"string"},"communityId":{"type":"string"},"status":{"type":"string","enum":["approved","pending","rejected"]},"title":{"type":"string"},"date":{"type":"string","format":"date-time"},"location":{"type":"string","nullable":true},"link":{"type":"string","format":"uri","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","communityId","status","title","date","createdAt"]},"Error":{"type":"object","properties":{"error":{"type":"string"},"fieldErrors":{"type":"object","additionalProperties":{"type":"string"}}},"required":["error"]}}}}