REST API Documentation

Complete documentation for integrating the Ludiks REST API

Base URL

https://api.ludiks.io

Authentication

All requests require your API key in the Authorization header

Authorization: Bearer ldk_live_abc123...

Replace YOUR_API_KEY with your actual API key

Endpoints

POST/end-user

Create or update a user in your project

Headers

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Request Body

idRequired

string

Unique user identifier

fullNameOptional

string

User's full name

emailOptional

string

User's email address

Example Request

curl -X POST https://api.ludiks.io/end-user \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "id": "user-123",
    "fullName": "John Doe",
    "picture": "https://example.com/picture.jpg",
    "email": "john@example.com"
  }'

Response (201 Created)

{
  "success": true,
  "user": {
    "id": "user-123",
    "fullName": "John Doe",
    "picture": "https://example.com/picture.jpg",
    "email": "john@example.com",
    "externalId": "user-123",
    "metadata": {},
    "createdAt": "2024-01-01T00:00:00Z",
    "lastLoginAt": "2024-01-01T00:00:00Z"
  }
}

POST/tracking

Send an event to track user progress

Headers

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Request Body

userIdRequired

string

User identifier

eventNameRequired

string

Name of the event to track

valueOptional

number

Numeric value associated with the event

timestampOptional

string (ISO 8601)

Event timestamp

Example Request

curl -X POST https://api.ludiks.io/tracking \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "user-123",
    "eventName": "purchase",
    "value": 99.99,
    "timestamp": "2024-01-20T15:30:00Z"
  }'

Response (200 OK)

{
  "success": true,
  "stepCompleted": true,
  "points": 150,
  "rewards": [
    {
      "name": "Big Spender",
      "description": "Made a significant purchase"
    }
  ],
  "circuitCompleted": false,
  "currentStreak": 5
}

GET/end-user/{userId}

Retrieve complete user profile and statistics

Headers

Authorization: Bearer YOUR_API_KEY

Path Parameters

userIdRequired

string

User identifier to retrieve

Example Request

curl -X GET https://api.ludiks.io/end-user/user-123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200 OK)

{
  "id": "user-123",
  "fullName": "John Doe",
  "email": "john@example.com",
  "externalId": "user-123",
  "currentStreak": 5,
  "longestStreak": 12,
  "metadata": {
    "plan": "premium",
    "signupSource": "website"
  },
  "circuitProgress": [
    {
      "id": "circuit-1",
      "circuitName": "Onboarding",
      "status": "completed",
      "points": 500,
      "startedAt": "2024-01-01T00:00:00Z",
      "completedAt": "2024-01-15T10:30:00Z"
    },
    {
      "id": "circuit-2",
      "circuitName": "Power User", 
      "status": "in_progress",
      "points": 250,
      "startedAt": "2024-01-16T00:00:00Z"
    }
  ],
  "createdAt": "2024-01-01T00:00:00Z",
  "lastLoginAt": "2024-01-20T15:30:00Z"
}

Error Responses

API error response format

400 Bad Request

{
  "error": "Invalid request",
  "message": "Missing required field: userId",
  "code": "VALIDATION_ERROR"
}

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key",
  "code": "AUTH_ERROR"
}

404 Not Found

{
  "error": "Not found",
  "message": "User not found",
  "code": "USER_NOT_FOUND"
}

Rate Limiting

API usage limits

• 1000 requests per hour per API key
• 100 requests per minute per API key
• Rate limit headers included in every response

Integration Examples

Complete Workflow with cURL

Example of a complete workflow from user creation to event tracking.

# 1. Create a new user
curl -X POST https://api.ludiks.io/end-user \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "id": "user-456",
    "fullName": "Alice Smith",
    "email": "alice@example.com"
  }'

# 2. Track user events
curl -X POST https://api.ludiks.io/tracking \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "user-456",
    "eventName": "signup_completed"
  }'

curl -X POST https://api.ludiks.io/tracking \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "user-456",
    "eventName": "purchase",
    "value": 49.99
  }'

# 3. Get user profile with progress
curl -X GET https://api.ludiks.io/end-user/user-456 \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript Integration

JavaScript integration example with error handling and utility functions.

const API_BASE = 'https://api.ludiks.io';
const API_KEY = 'your-api-key';

const headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer ' + API_KEY
};

async function createUser(userData) {
  const response = await fetch(API_BASE + '/end-user', {
    method: 'POST',
    headers,
    body: JSON.stringify(userData)
  });
  return response.json();
}

async function trackEvent(userId, eventName, value = null) {
  const response = await fetch(API_BASE + '/tracking', {
    method: 'POST',
    headers,
    body: JSON.stringify({
      userId,
      eventName,
      value,
      timestamp: new Date().toISOString()
    })
  });
  return response.json();
}

async function getUserProfile(userId) {
  const response = await fetch(API_BASE + '/end-user/' + userId, {
    headers
  });
  return response.json();
}

// Usage example
(async () => {
  try {
    // Create user
    const user = await createUser({
      id: 'user-789',
      fullName: 'Bob Johnson',
      email: 'bob@example.com'
    });
    
    // Track events
    const loginEvent = await trackEvent('user-789', 'login');
    const purchaseEvent = await trackEvent('user-789', 'purchase', 199.99);
    
    // Get profile
    const profile = await getUserProfile('user-789');
    console.log('User streak:', profile.currentStreak);
    
  } catch (error) {
    console.error('API Error:', error);
  }
})();

Next Steps