Skip to main content
The EngageFabric API is a RESTful API that allows you to integrate gamification features into your applications. All API endpoints are versioned and follow consistent patterns.

​
Base URL

https://api.engagefabric.cloud/api/v1

​
Authentication

All API requests require authentication via API key: 
curl -X GET "https://api.engagefabric.cloud/api/v1/players" \
  -H "X-API-Key: your-api-key"
See Authentication for detailed information.

​
Request Format

​
Headers

HeaderRequiredDescription
X-API-KeyYesYour project API key
Content-TypeYes*application/json for POST/PUT/PATCH
X-Idempotency-KeyNoUnique key for idempotent requests

​
Request Body

All request bodies should be JSON: 
{
  "externalUserId": "user-123",
  "displayName": "John Doe",
  "metadata": {
    "email": "john@example.com"
  }
}

​
Response Format

​
Success Response

{
  "id": "player-uuid",
  "externalUserId": "user-123",
  "displayName": "John Doe",
  "xp": 1500,
  "level": 5,
  "createdAt": "2025-01-21T10:00:00Z",
  "updatedAt": "2025-01-21T12:00:00Z"
}

​
Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "externalUserId",
        "message": "Must be a non-empty string"
      }
    ],
    "requestId": "req-abc123",
    "timestamp": "2025-01-21T10:00:00Z"
  }
}

​
HTTP Status Codes

StatusDescription
200 OKRequest succeeded
201 CreatedResource created successfully
400 Bad RequestInvalid request parameters
401 UnauthorizedMissing or invalid authentication
403 ForbiddenInsufficient permissions
404 Not FoundResource not found
409 ConflictResource already exists
429 Too Many RequestsRate limit exceeded
500 Internal Server ErrorServer error

​
Pagination

List endpoints support pagination: 
GET /api/v1/players?page=1&limit=20
Response: 
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

​
Filtering & Sorting

Many endpoints support filtering and sorting: 
# Filter by status
GET /api/v1/quests?status=ACTIVE

# Sort by creation date
GET /api/v1/players?sort=createdAt&order=desc

​
Idempotency

For POST requests, use the X-Idempotency-Key header to ensure idempotent operations: 
curl -X POST "https://api.engagefabric.cloud/api/v1/events" \
  -H "X-API-Key: your-api-key" \
  -H "X-Idempotency-Key: unique-request-id" \
  -H "Content-Type: application/json" \
  -d '{"name": "purchase_completed", "playerId": "..."}'
Idempotency keys are valid for 24 hours. Requests with the same key within this window will return the same response.

​
API Endpoints

Players

Manage player profiles, XP, levels, and currencies

Events

Track player actions and trigger gamification rules

Quests

Create and manage quest progress

Adventures

Seasonal content and quest collections

Leaderboards

Real-time rankings and competitions

Lobbies

Multiplayer lobby management

Chat

Real-time messaging

Rules

Configure gamification logic

​
SDKs

We provide official SDKs for easier integration:
LanguagePackageDocumentation
JavaScript/TypeScript@engagefabric/sdkSDK Docs
React@engagefabric/reactReact Docs

​
OpenAPI Specification

Download the complete OpenAPI specification:

OpenAPI Spec

Download the OpenAPI 3.0 specification for code generation and API exploration