# ThrillWiki API Documentation v1 ## Complete Frontend Developer Reference **Base URL**: `/api/v1/` **Authentication**: JWT Bearer tokens **Content-Type**: `application/json` --- ## πŸ” Authentication Endpoints (`/api/v1/auth/`) ### Core Authentication - **POST** `/auth/login/` - User login with username/email and password - **POST** `/auth/signup/` - User registration (email verification required) - **POST** `/auth/logout/` - Logout current user (blacklist refresh token) - **GET** `/auth/user/` - Get current authenticated user information - **POST** `/auth/status/` - Check authentication status ### Password Management - **POST** `/auth/password/reset/` - Request password reset email - **POST** `/auth/password/change/` - Change current user's password ### Email Verification - **GET** `/auth/verify-email//` - Verify email with token - **POST** `/auth/resend-verification/` - Resend email verification ### Social Authentication - **GET** `/auth/social/providers/` - Get available social auth providers - **GET** `/auth/social/providers/available/` - Get available social providers list - **GET** `/auth/social/connected/` - Get user's connected social providers - **POST** `/auth/social/connect//` - Connect social provider (Google, Discord) - **POST** `/auth/social/disconnect//` - Disconnect social provider - **GET** `/auth/social/status/` - Get comprehensive social auth status - **POST** `/auth/social/` - Social auth endpoints (dj-rest-auth) ### JWT Token Management - **POST** `/auth/token/refresh/` - Refresh JWT access token --- ## 🏞️ Parks API Endpoints (`/api/v1/parks/`) ### Core CRUD Operations - **GET** `/parks/` - List parks with comprehensive filtering and pagination - **POST** `/parks/` - Create new park (authenticated users) - **GET** `/parks//` - Get park details (supports ID or slug) - **PATCH** `/parks//` - Update park (partial update) - **PUT** `/parks//` - Update park (full update) - **DELETE** `/parks//` - Delete park ### Filtering & Search - **GET** `/parks/filter-options/` - Get available filter options - **GET** `/parks/search/companies/?q=` - Search companies/operators - **GET** `/parks/search-suggestions/?q=` - Get park search suggestions - **GET** `/parks/hybrid/` - Hybrid park filtering with advanced options - **GET** `/parks/hybrid/filter-metadata/` - Get filter metadata for hybrid filtering ### Park Photos Management - **GET** `/parks//photos/` - List park photos - **POST** `/parks//photos/` - Upload park photo - **GET** `/parks//photos//` - Get park photo details - **PATCH** `/parks//photos//` - Update park photo - **DELETE** `/parks//photos//` - Delete park photo - **POST** `/parks//photos//set_primary/` - Set photo as primary - **POST** `/parks//photos/bulk_approve/` - Bulk approve/reject photos (admin) - **GET** `/parks//photos/stats/` - Get park photo statistics ### Park Settings - **GET** `/parks//image-settings/` - Get park image settings - **POST** `/parks//image-settings/` - Update park image settings #### Park Filtering Parameters (24 total): - **Pagination**: `page`, `page_size` - **Search**: `search` - **Location**: `continent`, `country`, `state`, `city` - **Attributes**: `park_type`, `status` - **Companies**: `operator_id`, `operator_slug`, `property_owner_id`, `property_owner_slug` - **Ratings**: `min_rating`, `max_rating` - **Ride Counts**: `min_ride_count`, `max_ride_count` - **Opening Year**: `opening_year`, `min_opening_year`, `max_opening_year` - **Roller Coasters**: `has_roller_coasters`, `min_roller_coaster_count`, `max_roller_coaster_count` - **Ordering**: `ordering` --- ## 🎒 Rides API Endpoints (`/api/v1/rides/`) ### Core CRUD Operations - **GET** `/rides/` - List rides with comprehensive filtering - **POST** `/rides/` - Create new ride - **GET** `/rides//` - Get ride details - **PATCH** `/rides//` - Update ride (partial) - **PUT** `/rides//` - Update ride (full) - **DELETE** `/rides//` - Delete ride ### Filtering & Search - **GET** `/rides/filter-options/` - Get available filter options - **GET** `/rides/search/companies/?q=` - Search ride companies - **GET** `/rides/search/ride-models/?q=` - Search ride models - **GET** `/rides/search-suggestions/?q=` - Get ride search suggestions - **GET** `/rides/hybrid/` - Hybrid ride filtering - **GET** `/rides/hybrid/filter-metadata/` - Get ride filter metadata ### Ride Photos Management - **GET** `/rides//photos/` - List ride photos - **POST** `/rides//photos/` - Upload ride photo - **GET** `/rides//photos//` - Get ride photo details - **PATCH** `/rides//photos//` - Update ride photo - **DELETE** `/rides//photos//` - Delete ride photo - **POST** `/rides//photos//set_primary/` - Set photo as primary ### Ride Manufacturers - **GET** `/rides/manufacturers//` - Manufacturer-specific endpoints ### Ride Settings - **GET** `/rides//image-settings/` - Get ride image settings - **POST** `/rides//image-settings/` - Update ride image settings --- ## πŸ‘€ User Accounts API (`/api/v1/accounts/`) ### User Management (Admin) - **DELETE** `/accounts/users//delete/` - Delete user while preserving submissions - **GET** `/accounts/users//deletion-check/` - Check user deletion eligibility ### Self-Service Account Management - **POST** `/accounts/delete-account/request/` - Request account deletion - **POST** `/accounts/delete-account/verify/` - Verify account deletion - **POST** `/accounts/delete-account/cancel/` - Cancel account deletion ### User Profile Management - **GET** `/accounts/profile/` - Get user profile - **PATCH** `/accounts/profile/account/` - Update user account info - **PATCH** `/accounts/profile/update/` - Update user profile ### User Preferences - **GET** `/accounts/preferences/` - Get user preferences - **PATCH** `/accounts/preferences/update/` - Update user preferences - **PATCH** `/accounts/preferences/theme/` - Update theme preference ### Settings Management - **GET** `/accounts/settings/notifications/` - Get notification settings - **PATCH** `/accounts/settings/notifications/update/` - Update notification settings - **GET** `/accounts/settings/privacy/` - Get privacy settings - **PATCH** `/accounts/settings/privacy/update/` - Update privacy settings - **GET** `/accounts/settings/security/` - Get security settings - **PATCH** `/accounts/settings/security/update/` - Update security settings ### User Statistics & Lists - **GET** `/accounts/statistics/` - Get user statistics - **GET** `/accounts/top-lists/` - Get user's top lists - **POST** `/accounts/top-lists/create/` - Create new top list - **PATCH** `/accounts/top-lists//` - Update top list - **DELETE** `/accounts/top-lists//delete/` - Delete top list ### Notifications - **GET** `/accounts/notifications/` - Get user notifications - **POST** `/accounts/notifications/mark-read/` - Mark notifications as read - **GET** `/accounts/notification-preferences/` - Get notification preferences - **PATCH** `/accounts/notification-preferences/update/` - Update notification preferences ### Avatar Management - **POST** `/accounts/profile/avatar/upload/` - Upload avatar - **POST** `/accounts/profile/avatar/save/` - Save avatar image - **DELETE** `/accounts/profile/avatar/delete/` - Delete avatar --- ## πŸ—ΊοΈ Maps API (`/api/v1/maps/`) ### Location Data - **GET** `/maps/locations/` - Get map locations data - **GET** `/maps/locations///` - Get location details - **GET** `/maps/search/` - Search locations on map - **GET** `/maps/bounds/` - Query locations within bounds ### Map Services - **GET** `/maps/stats/` - Get map service statistics - **GET** `/maps/cache/` - Get map cache information - **POST** `/maps/cache/invalidate/` - Invalidate map cache --- ## πŸ” Core Search API (`/api/v1/core/`) ### Entity Search - **GET** `/core/entities/search/` - Fuzzy search for entities - **GET** `/core/entities/not-found/` - Handle entity not found - **GET** `/core/entities/suggestions/` - Quick entity suggestions --- ## πŸ“§ Email API (`/api/v1/email/`) ### Email Services - **POST** `/email/send/` - Send email --- ## πŸ“œ History API (`/api/v1/history/`) ### Park History - **GET** `/history/parks//` - Get park history - **GET** `/history/parks//detail/` - Get detailed park history ### Ride History - **GET** `/history/parks//rides//` - Get ride history - **GET** `/history/parks//rides//detail/` - Get detailed ride history ### Unified Timeline - **GET** `/history/timeline/` - Get unified history timeline --- ## πŸ“ˆ System & Analytics APIs ### Health Checks - **GET** `/api/v1/health/` - Comprehensive health check - **GET** `/api/v1/health/simple/` - Simple health check - **GET** `/api/v1/health/performance/` - Performance metrics ### Trending & Discovery - **GET** `/api/v1/trending/` - Get trending content - **GET** `/api/v1/new-content/` - Get new content - **POST** `/api/v1/trending/calculate/` - Trigger trending calculation ### Statistics - **GET** `/api/v1/stats/` - Get system statistics - **POST** `/api/v1/stats/recalculate/` - Recalculate statistics ### Reviews - **GET** `/api/v1/reviews/latest/` - Get latest reviews ### Rankings - **GET** `/api/v1/rankings/` - Get ride rankings with filtering - **GET** `/api/v1/rankings//` - Get detailed ranking for specific ride - **GET** `/api/v1/rankings//history/` - Get ranking history for ride - **GET** `/api/v1/rankings//comparisons/` - Get head-to-head comparisons - **GET** `/api/v1/rankings/statistics/` - Get ranking system statistics - **POST** `/api/v1/rankings/calculate/` - Trigger ranking calculation (admin) #### Rankings Filtering Parameters: - **category**: Filter by ride category (RC, DR, FR, WR, TR, OT) - **min_riders**: Minimum number of mutual riders required - **park**: Filter by park slug - **ordering**: Order results (rank, -rank, winning_percentage, -winning_percentage) --- ## πŸ›‘οΈ Moderation API (`/api/v1/moderation/`) ### Moderation Reports - **GET** `/moderation/reports/` - List all moderation reports - **POST** `/moderation/reports/` - Create new moderation report - **GET** `/moderation/reports//` - Get specific report details - **PUT** `/moderation/reports//` - Update moderation report - **PATCH** `/moderation/reports//` - Partial update report - **DELETE** `/moderation/reports//` - Delete moderation report - **POST** `/moderation/reports//assign/` - Assign report to moderator - **POST** `/moderation/reports//resolve/` - Resolve moderation report - **GET** `/moderation/reports/stats/` - Get report statistics ### Moderation Queue - **GET** `/moderation/queue/` - List moderation queue items - **POST** `/moderation/queue/` - Create queue item - **GET** `/moderation/queue//` - Get specific queue item - **PUT** `/moderation/queue//` - Update queue item - **PATCH** `/moderation/queue//` - Partial update queue item - **DELETE** `/moderation/queue//` - Delete queue item - **POST** `/moderation/queue//assign/` - Assign queue item to moderator - **POST** `/moderation/queue//unassign/` - Unassign queue item - **POST** `/moderation/queue//complete/` - Complete queue item - **GET** `/moderation/queue/my_queue/` - Get current user's queue items ### Moderation Actions - **GET** `/moderation/actions/` - List all moderation actions - **POST** `/moderation/actions/` - Create new moderation action - **GET** `/moderation/actions//` - Get specific action details - **PUT** `/moderation/actions//` - Update moderation action - **PATCH** `/moderation/actions//` - Partial update action - **DELETE** `/moderation/actions//` - Delete moderation action - **POST** `/moderation/actions//deactivate/` - Deactivate action - **GET** `/moderation/actions/active/` - Get active moderation actions - **GET** `/moderation/actions/expired/` - Get expired moderation actions ### Bulk Operations - **GET** `/moderation/bulk-operations/` - List bulk moderation operations - **POST** `/moderation/bulk-operations/` - Create bulk operation - **GET** `/moderation/bulk-operations//` - Get bulk operation details - **PUT** `/moderation/bulk-operations//` - Update bulk operation - **PATCH** `/moderation/bulk-operations//` - Partial update operation - **DELETE** `/moderation/bulk-operations//` - Delete bulk operation - **POST** `/moderation/bulk-operations//cancel/` - Cancel bulk operation - **POST** `/moderation/bulk-operations//retry/` - Retry failed operation - **GET** `/moderation/bulk-operations//logs/` - Get operation logs - **GET** `/moderation/bulk-operations/running/` - Get running operations ### User Moderation - **GET** `/moderation/users//` - Get user moderation profile - **POST** `/moderation/users//moderate/` - Take moderation action against user - **GET** `/moderation/users/search/` - Search users for moderation - **GET** `/moderation/users/stats/` - Get user moderation statistics --- ## πŸ—οΈ Ride Manufacturers & Models (`/api/v1/rides/manufacturers//`) ### Ride Models - **GET** `/rides/manufacturers//` - List ride models by manufacturer - **POST** `/rides/manufacturers//` - Create new ride model - **GET** `/rides/manufacturers///` - Get ride model details - **PATCH** `/rides/manufacturers///` - Update ride model - **DELETE** `/rides/manufacturers///` - Delete ride model ### Model Search & Filtering - **GET** `/rides/manufacturers//search/` - Search ride models - **GET** `/rides/manufacturers//filter-options/` - Get filter options - **GET** `/rides/manufacturers//stats/` - Get manufacturer statistics ### Model Variants - **GET** `/rides/manufacturers///variants/` - List model variants - **POST** `/rides/manufacturers///variants/` - Create variant - **GET** `/rides/manufacturers///variants//` - Get variant details - **PATCH** `/rides/manufacturers///variants//` - Update variant - **DELETE** `/rides/manufacturers///variants//` - Delete variant ### Technical Specifications - **GET** `/rides/manufacturers///technical-specs/` - List technical specs - **POST** `/rides/manufacturers///technical-specs/` - Create technical spec - **GET** `/rides/manufacturers///technical-specs//` - Get spec details - **PATCH** `/rides/manufacturers///technical-specs//` - Update spec - **DELETE** `/rides/manufacturers///technical-specs//` - Delete spec ### Model Photos - **GET** `/rides/manufacturers///photos/` - List model photos - **POST** `/rides/manufacturers///photos/` - Upload model photo - **GET** `/rides/manufacturers///photos//` - Get photo details - **PATCH** `/rides/manufacturers///photos//` - Update photo - **DELETE** `/rides/manufacturers///photos//` - Delete photo --- ## πŸ–ΌοΈ Media Management ### Cloudflare Images - **ALL** `/api/v1/cloudflare-images/` - Cloudflare Images toolkit endpoints --- ## πŸ“š API Documentation ### Interactive Documentation - **GET** `/api/schema/` - OpenAPI schema - **GET** `/api/docs/` - Swagger UI documentation - **GET** `/api/redoc/` - ReDoc documentation --- ## πŸ”§ Common Request/Response Patterns ### Authentication Headers ```javascript headers: { 'Authorization': 'Bearer ', 'Content-Type': 'application/json' } ``` ### Pagination Response ```json { "count": 100, "next": "http://api.example.com/api/v1/endpoint/?page=2", "previous": null, "results": [...] } ``` ### Error Response Format ```json { "error": "Error message", "error_code": "SPECIFIC_ERROR_CODE", "details": {...}, "suggestions": ["suggestion1", "suggestion2"] } ``` ### Success Response Format ```json { "success": true, "message": "Operation completed successfully", "data": {...} } ``` --- ## πŸ“ Key Data Models ### User - `id`, `username`, `email`, `display_name`, `date_joined`, `is_active`, `avatar_url` ### Park - `id`, `name`, `slug`, `description`, `location`, `operator`, `park_type`, `status`, `opening_year` ### Ride - `id`, `name`, `slug`, `park`, `category`, `manufacturer`, `model`, `opening_year`, `status` ### Photo (Park/Ride) - `id`, `image`, `caption`, `photo_type`, `uploaded_by`, `is_primary`, `is_approved`, `created_at` ### Review - `id`, `user`, `content_object`, `rating`, `title`, `content`, `created_at`, `updated_at` --- ## 🚨 Important Notes 1. **Authentication Required**: Most endpoints require JWT authentication 2. **Permissions**: Admin endpoints require staff/superuser privileges 3. **Rate Limiting**: May be implemented on certain endpoints 4. **File Uploads**: Use `multipart/form-data` for photo uploads 5. **Pagination**: Most list endpoints support pagination with `page` and `page_size` parameters 6. **Filtering**: Parks and rides support extensive filtering options 7. **Cloudflare Images**: Media files are handled through Cloudflare Images service 8. **Email Verification**: New users must verify email before full access --- ## πŸ“– Usage Examples ### Authentication Flow ```javascript // Login const login = await fetch('/api/v1/auth/login/', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ username: 'user@example.com', password: 'password' }) }); // Use tokens from response const { access, refresh } = await login.json(); ``` ### Fetch Parks with Filtering ```javascript const parks = await fetch('/api/v1/parks/?continent=NA&min_rating=4.0&page=1', { headers: { 'Authorization': `Bearer ${access_token}` } }); ``` ### Upload Park Photo ```javascript const formData = new FormData(); formData.append('image', file); formData.append('caption', 'Beautiful park entrance'); const photo = await fetch('/api/v1/parks/123/photos/', { method: 'POST', headers: { 'Authorization': `Bearer ${access_token}` }, body: formData }); ``` --- This documentation covers all available API endpoints in the ThrillWiki v1 API. For detailed request/response schemas, parameter validation, and interactive testing, visit `/api/docs/` when the development server is running.