API Reference

Welcome to the GatherGuard API. Our platform provides a Federated Trust & Safety Layer for community-driven applications. Build reputation systems, verify real-world attendance, and block high-risk actors.

Base URL: https://api.gatherguard.org/functions/v1

Federated Blocklist

Cross-community protection against known bad actors.

Web of Trust

PGP-style vouching for organic reputation building.

AI Moderation

Real-time toxicity & spam detection in milliseconds.

Authentication

Authenticate requests with your Organization API Key in the Authorization header.

Authorization: Bearer gg_8f7d2a...

Get Risk Score

Returns a user's trust score and checks their hashed identity against our Federated Blocklist. This is your primary defense against "Cold Start" abuse.

POST /trust-score

Request Body

Field	Type	Description
userId Required	string	Your internal user ID.
userEmail Optional	string	Required for Global Blocklist checks. We hash this (SHA-256) immediately.

Response

{
  "success": true,
  "trustScore": 75,
  "overallRisk": "medium",
  "recommendation": "review",
  "globalRiskLabel": "suspicious", 
  "blocklistMatch": {
    "risk_level": "suspicious",
    "reason": "Flagged for spam in 3 communities"
  }
}

Log Trust Event

Send raw signals about user behavior. Our engine handles point weighting and badge assignment automatically.

POST /trust-event

Event Types

attended_gathering → +5 pts
vouch_given → +10 pts
content_flagged → -15 pts
identity_verified → +10 pts

Verify Attendance

Log a verified meeting. This endpoint enforces duplicate checks and automatically awards bonuses for consistent participation.

Consistent Attendance Bonus: +10 pts after 4+ gatherings!

POST /verify-attendance

Request Body

Field	Type	Description
userId Required	string	User being verified.
meetingId Required	string	The gathering/event ID.
meetingType Required	string	One of: `gathering`, `prayer_group`, `bible_study`, `service`
verifiedBy Required	string	Leader or admin confirming attendance.

{ 
  "userId": "user_123",
  "meetingId": "gathering_456",
  "meetingType": "prayer_group",
  "verifiedBy": "leader_001"
}

Community Vouches

Allow members to "vouch" for each other, building a Web of Trust similar to PGP key signing. Different vouch types award different trust points.

POST /vouches

Create Vouch

Vouch Type	Points	Use Case
`general`	+5 pts	General character reference
`safety`	+10 pts	Trusted around vulnerable groups
`hospitality`	+8 pts	Reliable host/helper
`spiritual`	+8 pts	Spiritual maturity

{ 
  "voucherUserId": "leader_001",
  "voucheeUserId": "new_user_55",
  "vouchType": "safety",
  "message": "Known them for 2 years."
}

GET /vouches?userId=user_123

Get User Vouches

Returns a list of all users who have vouched for this ID, including vouch types and timestamps.

Shared Experiences

Find gathering overlaps between two users. Perfect for "Suggested Connections" features or verifying if two users actually know each other from real-world events.

POST /shared-experiences

{ 
  "user1Id": "alice", 
  "user2Id": "bob" 
}

Response

{
  "sharedGatherings": [
    { "gatheringId": "g_001", "title": "Sunday Service - Dec 1" },
    { "gatheringId": "g_015", "title": "Prayer Night" }
  ],
  "overlapCount": 2
}

AI Content Analysis

Analyze text for toxicity, spam, and PII in milliseconds. Can optionally deduct score automatically when violations are detected.

POST /moderate-content

{ 
  "text": "Buy crypto now!", 
  "userId": "spammer_01"
}

Response

{
  "flagged": true,
  "categories": ["spam", "solicitation"],
  "confidence": 0.94,
  "action": "auto_hidden"
}

Batch Moderation

Analyze up to 100 items at once. Perfect for importing historical data or processing busy chat streams efficiently.

POST /batch-moderate

{
  "items": [
    { "contentId": "msg_1", "text": "Hello world", "userId": "u1" },
    { "contentId": "msg_2", "text": "Buy crypto now!", "userId": "u2" },
    { "contentId": "msg_3", "text": "Great sermon today!", "userId": "u3" }
  ]
}

Response

{
  "results": [
    { "contentId": "msg_1", "flagged": false },
    { "contentId": "msg_2", "flagged": true, "categories": ["spam"] },
    { "contentId": "msg_3", "flagged": false }
  ],
  "processed": 3,
  "flaggedCount": 1
}

Manual Flagging

Allow users to manually report content. These flags enter the Moderation Queue for human review.

POST /content-flag

{
  "reporterUserId": "user_a",
  "contentId": "post_b",
  "reason": "harassment"
}

Moderation Queue

Fetch pending flags for your admin dashboard. Filter by status and paginate results.

POST /moderation-queue

{ 
  "status": "pending",
  "limit": 50 
}

Status Options

pending — Awaiting review
reviewed — Seen but no action taken
actioned — Action was taken (removed, warned, etc.)

Webhooks & Security

GatherGuard sends webhooks for events like score.threshold_reached or user.banned. To ensure these requests are actually from us, you must verify the HMAC signature.

SECURITY Verifying Signatures

Every webhook request includes a X-GatherGuard-Signature header. Compute the HMAC-SHA256 of the JSON body using your Webhook Secret.

Node.js Example

import { createHmac } from 'crypto';

// 1. Get the signature from headers
const signature = req.headers['x-gatherguard-signature'];

// 2. Get the raw body
const payload = JSON.stringify(req.body);

// 3. Compute expected signature
const expectedSignature = createHmac('sha256', process.env.WEBHOOK_SECRET)
  .update(payload)
  .digest('hex');

// 4. Compare
if (signature !== expectedSignature) {
  throw new Error('Invalid signature - Request rejected');
}