← Home

API Documentation

Base: http://localhost:3002
Auth: All protected routes require a valid session cookie (web) or Bearer token (mobile). Unauthenticated requests return 401 Unauthorized. Public routes are marked public.

System

Health checks and developer portal APIs

GET/api/healthpublic

Health check. Returns status and timestamp.

GET/api/backlogpublic

List all backlog items.

POST/api/backlogpublic

Log a new backlog item from any session.

Parameters
titlebodyrequiredShort description of the item
typebodyrequiredfeature | bug | enhancement | question
prioritybodyrequiredhigh | medium | low
sessionbodyrequiredWhich session is logging: api | web | mobile | onboarding | account-portal
descriptionbodyoptionalFull description
apiEndpointbodyoptionalRelated endpoint e.g. POST /api/communities
statusbodyoptionalopen (default) | in-progress | done
PATCH/api/backlog/:idpublic

Update a backlog item (status, priority, etc).

Parameters
idpathrequiredBacklog item ID
DELETE/api/backlog/:idpublic

Delete a backlog item.

Parameters
idpathrequiredBacklog item ID

Users

User sync between Clerk and local DB

POST/api/users/sync

Sync the Clerk user to the local users table. Call this on first app launch after sign-in.

Idempotent. Safe to call on every login. Creates user if not found, updates displayName and avatarUrl if changed.

Communities

Top-level tenant — one account can own many communities

GET/api/communities

List all communities the current user belongs to.

POST/api/communities

Create a new community. Creator becomes owner.

Parameters
namebodyrequiredCommunity name (2–100 chars)
descriptionbodyoptionalShort description (max 500 chars)
isPrivatebodyoptionalBoolean — defaults to false
Also creates a Stream Chat channel for community-wide announcements.
GET/api/communities/:id

Get a community by ID.

Parameters
idpathrequiredCommunity UUID
Private communities are only visible to members.
PATCH/api/communities/:id

Update community metadata. Requires owner or admin role.

Parameters
idpathrequiredCommunity UUID
namebodyoptionalNew name
descriptionbodyoptionalNew description
logoUrlbodyoptionalVercel Blob URL
coverImageUrlbodyoptionalVercel Blob URL
isPrivatebodyoptionalBoolean
DELETE/api/communities/:id

Delete a community. Owner only.

Parameters
idpathrequiredCommunity UUID

Members

Community membership, directory, roles, and invites

GET/api/communities/:id/members

Get the full member directory for a community.

Parameters
idpathrequiredCommunity UUID
Returns user profile + role + status + joinedAt for each member.
PATCH/api/communities/:id/members

Update a member's role. Requires owner or admin.

Parameters
idpathrequiredCommunity UUID
targetUserIdbodyrequiredUser ID of the target member
rolebodyrequiredowner | admin | moderator | member
DELETE/api/communities/:id/members

Remove a member or leave a community.

Parameters
idpathrequiredCommunity UUID
targetUserIdbodyrequiredUser ID. Pass own ID to self-leave.
POST/api/communities/:id/invite

Send an invite link to an email address.

Parameters
idpathrequiredCommunity UUID
emailbodyrequiredEmail to invite
rolebodyoptionaladmin | moderator | member (default: member)
Returns invite token. Token expires after 7 days. Email delivery via Resend (TODO).
GET/api/members/:id/profile

Get a member's profile.

Parameters
idpathrequiredUser ID
PATCH/api/members/:id/profile

Update own profile. Users can only edit their own.

Parameters
idpathrequiredUser ID (must match authenticated user)
displayNamebodyoptional2–80 chars
biobodyoptionalMax 500 chars
phoneNumberbodyoptionalMax 20 chars
avatarUrlbodyoptionalVercel Blob URL

Groups

Sub-groups within a community — each maps to a Stream Chat channel

GET/api/groups?communityId=:id

List all groups in a community.

Parameters
communityIdqueryrequiredCommunity UUID
POST/api/groups

Create a group. Requires owner or admin role.

Parameters
communityIdbodyrequiredCommunity UUID
namebodyrequired2–80 chars
descriptionbodyoptionalMax 300 chars
isPrivatebodyoptionalBoolean — defaults to false
Creates a Stream Chat channel automatically. Creator is added as group admin.
GET/api/groups/:id

Get a group by ID.

Parameters
idpathrequiredGroup UUID
PATCH/api/groups/:id

Update group metadata. Requires group admin.

Parameters
idpathrequiredGroup UUID
DELETE/api/groups/:id

Delete group and its Stream channel.

Parameters
idpathrequiredGroup UUID
Requires group admin or community owner/admin.
POST/api/groups/:id

Add a member to the group.

Parameters
idpathrequiredGroup UUID
targetUserIdbodyrequiredUser ID to add
Requires group admin. Also adds member to the Stream channel.

Posts

Announcements and content — community-wide or group-scoped

GET/api/posts?communityId=:id&groupId=:id

List posts. Filter by community or group.

Parameters
communityIdqueryrequiredCommunity UUID
groupIdqueryoptionalGroup UUID — omit for community-wide feed
pagequeryoptionalPage number (default: 1)
limitqueryoptionalPer page (default: 20, max: 100)
Pinned posts always appear first.
POST/api/posts

Create an announcement or group post.

Parameters
communityIdbodyrequiredCommunity UUID
groupIdbodyoptionalGroup UUID — omit for community-wide post
contentbodyrequiredPost body (1–10,000 chars)
titlebodyoptionalOptional title (max 200 chars)
attachmentsbodyoptionalArray of Vercel Blob URLs (max 10)
isPinnedbodyoptionalBoolean — only admin/mod/owner can pin
GET/api/posts/:id

Get a post by ID.

Parameters
idpathrequiredPost UUID
PATCH/api/posts/:id

Edit a post. Author only.

Parameters
idpathrequiredPost UUID
DELETE/api/posts/:id

Delete a post. Author or community admin/mod/owner.

Parameters
idpathrequiredPost UUID

Stream Chat

Real-time messaging — clients connect to Stream directly using a JWT

POST/api/stream/token

Generate a Stream Chat JWT for the current user.

Returns { token, userId, apiKey }. Use these to initialise the Stream Chat client on web or mobile. Messages never pass through this API — clients connect to Stream directly.
community-cloud-api · API Documentation · 5/19/2026