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

Provider	Endpoint	Status
Email/Password	`/api/auth/sign-in/email`	Active
Google	`/api/auth/sign-in/social?provider=google`	Optional
GitHub	`/api/auth/sign-in/social?provider=github`	Optional

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

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Authentication required
`FORBIDDEN`	403	Insufficient permissions
`BAD_REQUEST`	400	Invalid request parameters
`NOT_FOUND`	404	Resource not found
`CONFLICT`	409	Resource conflict
`VALIDATION_ERROR`	400	Input validation failed
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`INTERNAL_ERROR`	500	Server error

Rate Limiting

RippleCore implements tiered rate limiting:

Tier	Limit	Use Case
PUBLIC	30/min	Anonymous endpoints, health checks
AUTHENTICATED	100/min	Standard CRUD operations
HEAVY	5/min	Exports, 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

Module	Endpoints	Description
Kindness	5	Peer recognition tracking
Volunteer	7	Community impact hours
Donations	6	Charitable giving
Wellbeing	5	Employee surveys

Portals

Portal	Endpoints	Description
Charity	11	Partner management
Council	5	Supplier oversight
Consultant	7	Client portfolio

Administration

Category	Endpoints	Description
Users	5	User management
Organizations	4	Org settings
License	3	Subscription management
Admin	5	System 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.

​API Reference

​Base URL

​Authentication

​Session Headers

​OAuth Providers

​Response Format

​Success Response

​Error Response

​Error Codes

​Rate Limiting

​CSRF Protection

​Multi-Tenancy

​Endpoint Categories

​Evidence Modules

​Portals

​Administration

​Common Endpoints

​Kindness

​Volunteer

​Donations

​Wellbeing

​Pagination

​Filtering

​SDKs

TypeScript SDK

OpenAPI Spec

​Webhooks

​Support

API Reference

Base URL

Authentication

Session Headers

OAuth Providers

Response Format

Success Response

Error Response

Error Codes

Rate Limiting

CSRF Protection

Multi-Tenancy

Endpoint Categories

Evidence Modules

Portals

Administration

Common Endpoints

Kindness

Volunteer

Donations

Wellbeing

Pagination

Filtering

SDKs

Webhooks

Support