API Overview

PadawanForge provides a comprehensive REST API built on Cloudflare Workers, offering endpoints for authentication, player management, AI-powered NPCs, real-time chat, and administrative functions.

Base URL

Production: https://your-domain.com/api
Development: http://localhost:4321/api

Authentication

The API uses session-based authentication with cookies for most endpoints:

  • Public endpoints: Health checks, OAuth initiation
  • Authenticated endpoints: Require valid session cookie
  • WebSocket endpoints: Use session-based authentication for real-time features

Session Management

Sessions are stored in Cloudflare KV with the following characteristics:

  • Duration: 7 days
  • Storage: HttpOnly, Secure (production), SameSite=Lax cookies
  • Data: Player ID, UUID, provider, email, username, avatar, level, experience

API Categories

🔐 Authentication

  • OAuth2 integration (Google, Discord)
  • Session management
  • Connected account linking
  • Tutorial and registration completion

Base path: /api/auth/

👤 Player Management

  • Player profiles and data
  • User preferences and settings
  • Experience and progression tracking
  • Account management

Base paths: /api/players/, /api/user/

🤖 NPCs & AI

  • AI-powered non-player characters
  • Chat interactions with virtual tutors
  • Statement generation
  • AI provider configuration

Base paths: /api/npcs/, /api/ai/

🗨️ Chat & Messaging

  • Real-time lobby chat via WebSockets
  • Direct messaging between players (stored in the direct_messages table)
  • Notification system
  • Message read status tracking

Base paths: /api/lobby/, /api/messages/, /api/notifications/

📁 File Management

  • File uploads to Cloudflare R2
  • Avatar management with multiple sizes
  • Rate-limited with size restrictions

Base paths: /api/files/, /api/avatars/

🎮 Demo System

  • Anonymous guest sessions
  • 24-hour temporary accounts
  • Demo-to-full account conversion
  • Usage analytics

Base path: /api/demo/

🛠️ Administration

  • Bot token management
  • MCP server configuration
  • System monitoring and debugging
  • User management tools

Base paths: /api/admin/, /api/debug/

Response Format

All API endpoints return JSON responses with consistent structure:

Success Response

{
  "success": true,
  "data": { /* response data */ },
  "timestamp": "2024-01-15T10:30:00Z"
}

Error Response

{
  "error": "Error message",
  "details": "Additional error details",
  "timestamp": "2024-01-15T10:30:00Z"
}

Paginated Response

{
  "items": [ /* array of items */ ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

Data Models

Player Session

interface Player {
  uuid: string;              // Public identifier
  username: string;
  avatar: string;
  level: number;
  experience: number;
  provider: 'google' | 'discord';
  email: string;
  playerId: string;          // Internal ID
  registrationCompleted?: boolean;
  tutorialCompleted?: boolean;
}

NPC Structure

interface NPC {
  id: string;
  name: string;
  description: string;
  avatar: string;
  level: number;
  ai_provider: string;
  ai_model: string;
  temperature: number;
  max_tokens: number;
  personality_traits: string;
}

Rate Limits

  • File uploads: 50 files/hour, 500MB/hour total
  • Avatar uploads: 5MB max size per file
  • General files: 25MB max size per file

Security Features

  • Session-based authentication with secure cookies
  • Role-based access control with 5-level hierarchy (Guest to System Admin)
  • Granular permissions for fine-grained access control
  • CORS protection for same-origin requests
  • Input validation with JSON schema validation
  • File type validation for uploads
  • Privacy controls with granular data visibility settings

Admin Access Levels

  • Guest (0): Demo and docs access only
  • Padawan (1): Browse-only access to players, NPCs, games
  • Game Master (2): Create/remove NPCs and games
  • Guild Leader (3): Currently unused
  • System Admin (4): Full system configuration access

WebSocket Connections

Real-time features use WebSocket connections:

  • Chat lobbies: /api/lobby/[id]/websocket
  • Authentication: Session-based via cookies
  • Protocols: Standard WebSocket with JSON messaging

Error Codes

CodeDescription
200Success
400Bad Request - Invalid input
401Unauthorized - Invalid session
403Forbidden - Insufficient permissions
404Not Found - Resource doesn’t exist
429Too Many Requests - Rate limit exceeded
500Internal Server Error
504Gateway Timeout - Database timeout

Database Architecture

The API follows a segmented data architecture for better performance and privacy:

  • players: Core identity and authentication
  • player_profiles: Display names, avatars, and profile information
  • player_preferences: UI settings, themes, and user preferences
  • player_game_data: Levels, experience, achievements, and game progression
  • player_personal_info: Sensitive personal data with privacy controls

Getting Started

  1. Authentication: Start with OAuth endpoints in /api/auth/
  2. Player Data: Access player information via /api/players/ or /api/user/
  3. Game Features: Interact with NPCs via /api/npcs/ and chat via /api/lobby/
  4. File Uploads: Use /api/files/ or /api/avatars/ for asset management

For detailed endpoint documentation, see the specific API reference pages:

← NPC API Players API →
PadawanForge v1.4.1