← Home

API Documentation

Base: http://localhost:3002
Auth: All protected routes require a valid Clerk 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
targetUserIdbodyrequiredClerk user ID of the target member
rolebodyrequiredowner | admin | moderator | member
DELETE/api/communities/:id/members

Remove a member or leave a community.

Parameters
idpathrequiredCommunity UUID
targetUserIdbodyrequiredClerk user 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
idpathrequiredClerk user ID
PATCH/api/members/:id/profile

Update own profile. Users can only edit their own.

Parameters
idpathrequiredClerk user 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
targetUserIdbodyrequiredClerk user 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 · 3/24/2026