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.

Register an Expo push token for the authenticated user (Sprint 41).

Remove an Expo push token for the authenticated user (Sprint 41).

Service health check.

Get all communities with optional filters.

Return all distinct tags in use across active communities (Sprint 36).

Update community interest tags (admin only, Sprint 36). Tags are normalized to lowercase and deduplicated.

Update community geographic coordinates (admin only, Sprint 36). Enables geography-mode discovery and distance sorting.

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.

Returns active trust questionnaire questions with choices, ordered by `display_order`. Public endpoint — no auth required.

Create a trust question. Platform admin only.

Update question text, subtext, display_order, or active status. Platform admin only.

Deactivate a trust question (sets active=false). Platform admin only.

Add a choice to a question. Platform admin only.

Update a choice's label, description, config_delta, or display_order. Platform admin only.

Remove a choice permanently. Platform admin only.

Get all help requests with optional filters.

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

Get curated feed scored on 7 signals: skill match, trust distance, community relevance, urgency, requester trust, prior interaction, and recency. Response includes `priorInteractionScore` and `recenc

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).

Boost a request for 48 hours, adding a +0.3 feed score bonus via the feed-service boost scoring rule (Sprint 36). Admin only.

Remove an active boost from a request (Sprint 36). Admin only.

Admin proposes a specific community member as a helper (Sprint 36). Creates a real `requests.matches` row with `status='proposed'`.

Toggle request urgency between `urgent` and `medium` (Sprint 36). Admin only.

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

List pending provider offers on a specific help request. Requester only.

Accept a pending provider offer. Creates a match between the requester and the provider.

Decline a pending provider offer.

Submit a provider offer on an open help request.

List offers submitted by the authenticated provider.

Withdraw a pending provider offer.

Returns the top-scored dibs candidate for a scheduled request. Returns `null` if no eligible candidate exists.

Send dibs to a specific provider. Only valid for scheduled requests.

Provider accepts dibs. Creates a `requests.matches` record directly and sets request status to `matched`.

Provider declines dibs. Reverts request status to `open` for public broadcast.

Returns the authenticated provider's pending dibs records (status = `pending`).

TEST-ONLY: Force-expire a dibs record regardless of `expires_at`. Sets status to `expired` and reverts request to `open`.

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)

List active rate cards for a provider (public). Owner can pass `?include_inactive=true` to include deactivated cards.

Create a new rate card for a provider. Auth: owner only. Body: `{ label, pricing_model, rate_amount?, rate_unit?, currency?, notes? }`.

Update an existing rate card. Auth: owner only.

Soft-delete a rate card — sets `is_active = false`. Auth: owner only. Card remains in database for historical reference.

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.

Get user trust config and effective parameters (merged community defaults + per-user overrides).

Toggle `evolution_enabled` for a user in a community (user or admin).

Return the immutable evolution log for a user — every parameter adjustment with trigger signal and event ID.

Get community-level evolution status (admin only). Returns whether evolution is enabled and the community cross_community_prior.

Toggle community evolution on/off (admin only).

Admin — paginated community evolution log showing parameter changes over time.

Admin — drift summary: first evolution date, evolved parameter count, last contributing member count.

Admin — enable/disable community evolution engine. Body: `{ "enabled": boolean }`.

Returns blended trust params from Redis cache (4h TTL), falls back to DB on cache miss. Auth: self only.

Returns the user's global evolution opt-in preference. Missing row = true (default opt-in). Auth: self only.

Set global evolution enabled/disabled for the user. Body: `{ "global_evolution_enabled": boolean }`. Auth: self only.

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.

Send Expo push notifications to a list of users. Internal use only (called by event handlers within the notification service itself, not exposed publicly).

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).

Get the current user's local network graph from the materialized connections table.