API Reference

Register a new user account.

Authenticate user and receive JWT token.

Verify JWT token and return user info.

Get user profile by ID.

Update user profile.

Get user's request type subscriptions (v9.0).

Update a single request type subscription.

Bulk update request type subscriptions.

Get user's interest categories (service_category, item_category, event_type).

Add a new interest.

Remove an interest.

Get user's feed visibility preferences for multi-tier feed.

Update user's feed visibility preferences.

Service health check.

Get all communities with optional filters.

Get communities the user is a member of.

Get specific community with all members.

Create new community.

Update community details (admin only).

Archive community (admin only, soft delete).

Get all members of a community.

Join a community (public: immediate, private: pending approval).

Add member to community (invite).

Update member role or status.

Remove member from community (self-leave or admin kick).

Get all norms for a community.

Get specific norm with all approvals.

Propose a new community norm.

Approve a proposed norm (requires simple majority >50% of members).

Archive a norm (admin or creator only).

Get community configuration.

Update community configuration (founder only for Phase 1).

Browse available configuration templates.

Copy configuration from another community.

Browse configurations from thriving communities.

Service health check.

Propose a link from this community to another (admin-only). Creates a `pending` link awaiting approval by the other community's admin.

Approve a pending link (other community's admin), or update `trust_carry_factor`/`show_in_sister_feeds`. Use `action: "approve"` or `action: "deactivate"` in the body.

List all links involving this community. Optional `?status=pending|active|inactive` filter. Returns `partner_community_id` and `partner_community_name` for convenience.

Remove a link (sets status to `inactive`). Either community's admin can do this.

Get all help requests with optional filters.

Get requests matching user's skills from their communities (skill-based matching algorithm).

Get curated feed with match scores, trust distance, and multi-tier visibility.

Get specific request details.

Create new polymorphic help request (supports 5 types) with visibility scope.

Update help request (requester only).

Cancel help request (requester only).

Update privacy settings for a request (Social Karma v2.0).

Override request urgency and/or add a community-scoped admin note (Sprint 25).

Get all help offers with optional filters.

Get specific offer details.

Create new help offer.

Update privacy settings for an offer (Social Karma v2.0).

Get all matches with optional filters.

Get specific match details.

Create a match between request and responder.

Two-phase match completion. Each party calls this independently; the match

Submit interaction feedback for a completed match.

Get feedback for a match.

List all provider profiles. Optional query param: service_type.

Get the authenticated user's own provider profiles. Auth required.

Get a single provider profile by ID, including ride details if applicable.

Create a provider profile for the authenticated user.

Update a provider profile. Owner only.

Delete a provider profile. Owner only.

List all provider collectives. Optional query param: service_type.

Get collectives the authenticated user belongs to (via their provider profiles). Auth required.

Get a collective with members and communities served.

Create a new provider collective.

Update a collective. Collective admin only.

Delete a collective. Collective admin only.

Join a collective as a member.

Remove a member from a collective. Collective admin only.

Link a collective to a community.

Unlink a collective from a community. Auth: collective admin OR community admin (Sprint 26).

Returns aggregate performance stats for a collective: `total_requests_matched`, `fulfillment_rate`, `avg_completion_hours` (null if no completed matches), `communities_served_count`, `available_membe

Toggle a provider's availability status. Body: `{ is_available: boolean }`. Auth: owner only (provider_profiles.user_id must match JWT userId). Returns `{ id, is_available }`. (Sprint 26)

Service health check.

Get user's total karma across all communities.

Get user's overall trust score — weighted average across all communities, weighted by recent interaction count.

Get user's trust score in a specific community.

Get top karma earners in a community.

Get karma transaction history for a user.

Get all prestige badges earned by a user (public). Phase 1 badge types: `first_helper`, `milestone_10`, `milestone_50`, `milestone_100`, `connector`.

Get community health metrics and trends.

Get community milestone achievements.

Enhanced trust score with interaction quality (UPDATED).

Get the network cohesion score for a community (ADR-045). Four graph topology metrics — reciprocity, density, clustering coefficient, and path score — over a rolling 90-day window.

Get the community trust score (ADR-040). Computed daily; recalculates on demand if no score exists yet.

Submit a private quality rating after a completed interaction. Ratings are internal trust signals — never exposed to users (ADR-036).

Service health check.

Server-Sent Events (SSE) endpoint for real-time notifications.

Get user's notifications (paginated).

Get count of unread notifications.

Mark specific notification as read.

Mark all notifications as read for a user.

Delete a notification.

Get user's notification preferences.

Update user's global notification preferences.

Service health check.

Get all conversations for a user.

Get all messages in a conversation (paginated).

Create new conversation (usually auto-created when match occurs).

Mark all messages in conversation as read.

Get personalized feed for user.

Dismiss item from feed.

Get user's feed preferences.

Update feed preferences.

Health check endpoint.

Search for geocoded addresses. Returns cached results if available, otherwise calls Nominatim API and caches the result.

Manually cache a geocoding result (used by frontend for fire-and-forget caching).

Get cache statistics and analytics.

Remove expired cache entries (older than 30 days).

Generate a new invitation code for current user.

Accept an invitation code during user signup.

Get invitation history for current user.

Get inviter statistics for current user (gamification metrics).

Get shortest path between current user and target user.

Get paths for multiple target users (optimized for feed ranking).