Back to Home

API DOCUMENTATION

REST API for Elite plan subscribers
ELITE FEATURE
API access requires an Elite subscription. Upgrade in your dashboard.

CONTENTS

AUTHENTICATION

All API requests require authentication using an API key. Generate your API key from the Settings tab in your dashboard.

Getting Your API Key

  1. Go to your Dashboard → Settings tab
  2. Scroll to "API Access" section
  3. Click "Generate API Key"
  4. Copy the key (it's only shown once!)
Include your API key in the Authorization header:
Authorization Header
Authorization: Bearer rr_your_api_key_here
Example Request
curl -X GET "https://yourapp.com/api/v1/leaderboard" \
  -H "Authorization: Bearer rr_abc123xyz789"
Security Warning
Never expose your API key in client-side code. Only use it from your server.

RATE LIMITING

API requests are rate limited to ensure fair usage:
100
requests/minute
GET endpoints
50
requests/minute
POST endpoints
If you exceed the rate limit, you'll receive a 429 Too Many Requests response. Wait 60 seconds before retrying.

ERROR HANDLING

All error responses follow a consistent format:
Error Response Format
{
  "success": false,
  "error": "Error message describing what went wrong"
}

Common Error Codes

400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API key
403Forbidden - API access not enabled for your plan
404Not Found - Resource doesn't exist
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Something went wrong

ENDPOINTS

GET/api/v1/leaderboard
Get the leaderboard rankings for your community. Returns users sorted by XP.

Query Parameters

timeframe(string)- all_time (default), monthly, or weekly
limit(number)- Number of results (default: 50, max: 100)

Response

{
  "success": true,
  "data": {
    "timeframe": "all_time",
    "count": 3,
    "entries": [
      {
        "rank": 1,
        "user_id": "usr_abc123",
        "username": "TopPlayer",
        "total_xp": 15000,
        "monthly_xp": 3000,
        "weekly_xp": 800,
        "current_streak": 12,
        "best_streak": 30
      },
      ...
    ]
  }
}
GET/api/v1/profiles/:userId
Get detailed profile information for a specific user, including their achievements and rewards.

Query Parameters

userId(string)required- The Whop user ID (e.g., usr_xxx)

Response

{
  "success": true,
  "data": {
    "user_id": "usr_abc123",
    "username": "PlayerOne",
    "avatar": "https://...",
    "level": 15,
    "total_xp": 8500,
    "monthly_xp": 1200,
    "weekly_xp": 350,
    "reward_points": 4500,
    "current_streak": 7,
    "best_streak": 21,
    "last_claim_at": "2024-12-29T10:00:00Z",
    "achievements": [
      {
        "id": "ach_xxx",
        "title": "First Steps",
        "rarity": "common",
        "unlocked_at": "2024-12-01T00:00:00Z"
      }
    ],
    "rewards": [
      {
        "id": "rwd_xxx",
        "title": "10% Discount",
        "status": "fulfilled",
        "promo_code": "SAVE10ABC"
      }
    ]
  }
}
POST/api/v1/xp
Award XP to a user programmatically. Useful for custom integrations like Discord bots, referrals, or external triggers.

Request Body

user_id(string)required- The Whop user ID to award XP to
amount(number)required- Amount of XP to award (1-100,000)
description(string)- Description for the XP award (shown in activity feed)

Response

{
  "success": true,
  "data": {
    "user_id": "usr_abc123",
    "xp_awarded": 500,
    "rp_awarded": 500,
    "new_total_xp": 9000,
    "new_level": 16,
    "level_up": true
  }
}
Notes
  • XP is automatically converted to Reward Points based on your conversion ratio
  • If the user doesn't exist, a profile will be created automatically
  • Achievement checks run automatically after awarding XP
  • Discord notifications are sent for level-ups (if configured)
GET/api/v1/rewards
Get all rewards configured for your community.

Response

{
  "success": true,
  "data": {
    "count": 3,
    "rewards": [
      {
        "id": "rwd_xxx",
        "title": "10% Off Next Purchase",
        "description": "Get 10% off your next order",
        "required_xp": 1000,
        "rp_cost": 500,
        "stock_limit": 100,
        "stock_claimed": 23,
        "is_active": true,
        "reward_config": {
          "amount_off": 10,
          "promo_type": "percentage"
        }
      },
      ...
    ]
  }
}
GET/api/v1/achievements
Get all achievements (system + custom) for your community.

Response

{
  "success": true,
  "data": {
    "count": 15,
    "achievements": [
      {
        "id": "ach_xxx",
        "title": "First Steps",
        "description": "Earn your first 100 XP",
        "icon": "star",
        "rarity": "common",
        "criteria_type": "total_points",
        "criteria_value": 100,
        "xp_reward": 50,
        "rp_reward": 25,
        "is_system": true,
        "is_hidden": false
      },
      ...
    ]
  }
}

CODE EXAMPLES

JavaScript / Node.js

const API_KEY = 'rr_your_api_key';
const BASE_URL = 'https://yourapp.com/api/v1';

async function awardXP(userId, amount, description) {
  const response = await fetch(`${BASE_URL}/xp`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      user_id: userId,
      amount: amount,
      description: description,
    }),
  });

  return response.json();
}

// Award 100 XP for completing a survey
const result = await awardXP('usr_abc123', 100, 'Survey completion bonus');
console.log(result.data.level_up ? 'Level up!' : 'XP awarded');

Python

import requests

API_KEY = 'rr_your_api_key'
BASE_URL = 'https://yourapp.com/api/v1'

def award_xp(user_id, amount, description=None):
    response = requests.post(
        f'{BASE_URL}/xp',
        headers={
            'Authorization': f'Bearer {API_KEY}',
            'Content-Type': 'application/json',
        },
        json={
            'user_id': user_id,
            'amount': amount,
            'description': description,
        }
    )
    return response.json()

# Award XP for Discord activity
result = award_xp('usr_abc123', 50, 'Discord engagement')
print(f"New level: {result['data']['new_level']}")

NEED HELP?

Elite subscribers get dedicated support with a 12-hour SLA.
Contact Support