> ## Documentation Index
> Fetch the complete documentation index at: https://docs.engagefabric.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Complete EngageFabric REST API reference. Explore endpoints for players, events, quests, leaderboards, and achievements with interactive examples.

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.com/api/v1
```

## Authentication

All API requests require authentication via API key:

```bash theme={null}
curl -X GET "https://api.engagefabric.com/api/v1/players" \
  -H "X-API-Key: your-api-key"
```

See [Authentication](/authentication) for detailed information.

***

## Request Format

### Headers

| Header              | Required | Description                           |
| ------------------- | -------- | ------------------------------------- |
| `X-API-Key`         | Yes      | Your project API key                  |
| `Content-Type`      | Yes\*    | `application/json` for POST/PUT/PATCH |
| `X-Idempotency-Key` | No       | Unique key for idempotent requests    |

### Request Body

All request bodies should be JSON:

```json theme={null}
{
  "externalUserId": "user-123",
  "displayName": "John Doe",
  "metadata": {
    "email": "john@example.com"
  }
}
```

***

## Response Format

### Success Response

```json theme={null}
{
  "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

```json theme={null}
{
  "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

| Status                      | Description                       |
| --------------------------- | --------------------------------- |
| `200 OK`                    | Request succeeded                 |
| `201 Created`               | Resource created successfully     |
| `400 Bad Request`           | Invalid request parameters        |
| `401 Unauthorized`          | Missing or invalid authentication |
| `403 Forbidden`             | Insufficient permissions          |
| `404 Not Found`             | Resource not found                |
| `409 Conflict`              | Resource already exists           |
| `429 Too Many Requests`     | Rate limit exceeded               |
| `500 Internal Server Error` | Server error                      |

***

## Pagination

List endpoints support pagination:

```bash theme={null}
GET /api/v1/players?page=1&limit=20
```

**Response:**

```json theme={null}
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}
```

***

## Filtering & Sorting

Many endpoints support filtering and sorting:

```bash theme={null}
# 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:

```bash theme={null}
curl -X POST "https://api.engagefabric.com/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": "..."}'
```

<Info>
  Idempotency keys are valid for 24 hours. Requests with the same key within
  this window will return the same response.
</Info>

***

## API Endpoints

<CardGroup cols={2}>
  <Card title="Players" icon="user" href="/api-reference/players/overview">
    Manage player profiles, XP, levels, and currencies
  </Card>

  <Card title="Events" icon="bolt" href="/api-reference/events/overview">
    Track player actions and trigger gamification rules
  </Card>

  <Card title="Quests" icon="scroll" href="/api-reference/quests/overview">
    Create and manage quest progress
  </Card>

  <Card title="Adventures" icon="map" href="/api-reference/adventures/overview">
    Seasonal content and quest collections
  </Card>

  <Card title="Leaderboards" icon="trophy" href="/api-reference/leaderboards/overview">
    Real-time rankings and competitions
  </Card>

  <Card title="Lobbies" icon="users" href="/api-reference/lobbies/overview">
    Multiplayer lobby management
  </Card>

  <Card title="Chat" icon="comments" href="/api-reference/chat/overview">
    Real-time messaging
  </Card>

  <Card title="Rules" icon="gears" href="/api-reference/rules/overview">
    Configure gamification logic
  </Card>
</CardGroup>

***

## SDKs

We provide official SDKs for easier integration:

| Language              | Package                  | Documentation                |
| --------------------- | ------------------------ | ---------------------------- |
| JavaScript/TypeScript | `@engagefabricsdk/sdk`   | [SDK Docs](/sdks/javascript) |
| React                 | `@engagefabricsdk/react` | [React Docs](/sdks/react)    |

***

## OpenAPI Specification

Download the complete OpenAPI specification:

<Card title="OpenAPI Spec" icon="file-code" href="/api-reference/openapi.json">
  Download the OpenAPI 3.0 specification for code generation and API exploration
</Card>