​
API Reference

The RippleCore API provides programmatic access to all platform features, enabling integration with your existing systems.

​
Base URL

https://api.ripplecore.co.uk/v1
For development: 
http://localhost:3000/api

​
Authentication

RippleCore uses session-based authentication powered by Better Auth. All API requests require a valid session.

​
Session Headers

curl -X GET "https://api.ripplecore.co.uk/v1/kindness" \
  -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN"

​
OAuth Providers

ProviderEndpointStatus
Email/Password/api/auth/sign-in/emailActive
Google/api/auth/sign-in/social?provider=googleOptional
GitHub/api/auth/sign-in/social?provider=githubOptional

​
Response Format

All responses follow a consistent structure:

​
Success Response

{
  "success": true,
  "data": {
    // Response payload
  },
  "message": "Optional success message"
}

​
Error Response

{
  "success": false,
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "details": {
    // Optional error details
  }
}

​
Error Codes

CodeHTTP StatusDescription
UNAUTHORIZED401Authentication required
FORBIDDEN403Insufficient permissions
BAD_REQUEST400Invalid request parameters
NOT_FOUND404Resource not found
CONFLICT409Resource conflict
VALIDATION_ERROR400Input validation failed
RATE_LIMIT_EXCEEDED429Too many requests
INTERNAL_ERROR500Server error

​
Rate Limiting

RippleCore implements tiered rate limiting:
TierLimitUse Case
PUBLIC30/minAnonymous endpoints, health checks
AUTHENTICATED100/minStandard CRUD operations
HEAVY5/minExports, bulk operations, AI features
Rate limit headers are included in all responses: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000

​
CSRF Protection

All state-changing operations (POST, PUT, PATCH, DELETE) require CSRF tokens: 
# Get CSRF token
GET /api/auth/csrf

# Include in mutation requests
curl -X POST "https://api.ripplecore.co.uk/v1/kindness" \
  -H "X-CSRF-Token: YOUR_CSRF_TOKEN" \
  -H "Cookie: better-auth.session_token=YOUR_SESSION" \
  -d '{"toUserId": "..."}'

​
Multi-Tenancy

All requests are scoped to the user’s active organization. Include organization context via session: 
// Organization ID is extracted from session
const session = await auth.api.getSession({ headers });
const organizationId = session.session.activeOrganizationId;

​
Endpoint Categories

​
Evidence Modules

ModuleEndpointsDescription
Kindness5Peer recognition tracking
Volunteer7Community impact hours
Donations6Charitable giving
Wellbeing5Employee surveys

​
Portals

PortalEndpointsDescription
Charity11Partner management
Council5Supplier oversight
Consultant7Client portfolio

​
Administration

CategoryEndpointsDescription
Users5User management
Organizations4Org settings
License3Subscription management
Admin5System administration

​
Common Endpoints

​
Kindness

# List kindness acts
GET /api/kindness

# Create kindness act
POST /api/kindness
{
  "toUserId": "user_123",
  "description": "Helped with the project",
  "tags": ["teamwork"]
}

# Get statistics
GET /api/kindness/stats

​
Volunteer

# List opportunities
GET /api/volunteer/opportunities

# Sign up for opportunity
POST /api/volunteer/opportunities/{id}/signup

# Check in
POST /api/volunteer/check-in
{
  "opportunityId": "opp_123",
  "method": "gps",
  "location": { "lat": 51.5074, "lng": -0.1278 }
}

# Log hours
POST /api/volunteer/hours
{
  "opportunityId": "opp_123",
  "hours": 3,
  "outcome": "Completed beach cleanup"
}

​
Donations

# List donations
GET /api/donations

# Create donation
POST /api/donations
{
  "amount": 100,
  "currency": "GBP",
  "source": "payroll",
  "charityId": "charity_123",
  "giftAidEligible": true
}

# Get tax receipt
GET /api/donations/{id}/receipt

​
Wellbeing

# List surveys
GET /api/wellbeing/surveys

# Submit response
POST /api/wellbeing/surveys/{id}/respond
{
  "answers": [
    { "questionId": "q1", "value": 8 },
    { "questionId": "q2", "value": "Feeling good" }
  ]
}

​
Pagination

List endpoints support cursor-based pagination: 
GET /api/kindness?limit=20&cursor=abc123
Response includes pagination info: 
{
  "success": true,
  "data": [...],
  "pagination": {
    "hasMore": true,
    "nextCursor": "xyz789",
    "total": 150
  }
}

​
Filtering

Most list endpoints support filtering: 
# Filter by date range
GET /api/kindness?startDate=2025-01-01&endDate=2025-03-31

# Filter by user
GET /api/donations?userId=user_123

# Filter by status
GET /api/volunteer/opportunities?status=active

​
SDKs

TypeScript SDK

Official TypeScript/JavaScript client library

OpenAPI Spec

Download the OpenAPI 3.0 specification

​
Webhooks

RippleCore supports outbound webhooks for real-time event notifications. See Webhook Integration for setup instructions.

​
Support

For API support, contact api-support@ripplecore.co.uk or visit our GitHub repository.