thrillwiki_django_no_react/THRILLWIKI_API_DOCUMENTATION.md

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/<token>/ - 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/<provider>/ - Connect social provider (Google, Discord)
• POST /auth/social/disconnect/<provider>/ - 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/<pk>/ - Get park details (supports ID or slug)
• PATCH /parks/<pk>/ - Update park (partial update)
• PUT /parks/<pk>/ - Update park (full update)
• DELETE /parks/<pk>/ - Delete park

Filtering & Search

• GET /parks/filter-options/ - Get available filter options
• GET /parks/search/companies/?q=<query> - Search companies/operators
• GET /parks/search-suggestions/?q=<query> - 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/<park_pk>/photos/ - List park photos
• POST /parks/<park_pk>/photos/ - Upload park photo
• GET /parks/<park_pk>/photos/<id>/ - Get park photo details
• PATCH /parks/<park_pk>/photos/<id>/ - Update park photo
• DELETE /parks/<park_pk>/photos/<id>/ - Delete park photo
• POST /parks/<park_pk>/photos/<id>/set_primary/ - Set photo as primary
• POST /parks/<park_pk>/photos/bulk_approve/ - Bulk approve/reject photos (admin)
• GET /parks/<park_pk>/photos/stats/ - Get park photo statistics

Park Settings

• GET /parks/<pk>/image-settings/ - Get park image settings
• POST /parks/<pk>/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/<pk>/ - Get ride details
• PATCH /rides/<pk>/ - Update ride (partial)
• PUT /rides/<pk>/ - Update ride (full)
• DELETE /rides/<pk>/ - Delete ride

Filtering & Search

• GET /rides/filter-options/ - Get available filter options
• GET /rides/search/companies/?q=<query> - Search ride companies
• GET /rides/search/ride-models/?q=<query> - Search ride models
• GET /rides/search-suggestions/?q=<query> - Get ride search suggestions
• GET /rides/hybrid/ - Hybrid ride filtering
• GET /rides/hybrid/filter-metadata/ - Get ride filter metadata

Ride Photos Management

• GET /rides/<ride_pk>/photos/ - List ride photos
• POST /rides/<ride_pk>/photos/ - Upload ride photo
• GET /rides/<ride_pk>/photos/<id>/ - Get ride photo details
• PATCH /rides/<ride_pk>/photos/<id>/ - Update ride photo
• DELETE /rides/<ride_pk>/photos/<id>/ - Delete ride photo
• POST /rides/<ride_pk>/photos/<id>/set_primary/ - Set photo as primary

Ride Manufacturers

• GET /rides/manufacturers/<manufacturer_slug>/ - Manufacturer-specific endpoints

Ride Settings

• GET /rides/<pk>/image-settings/ - Get ride image settings
• POST /rides/<pk>/image-settings/ - Update ride image settings

---

👤 User Accounts API (/api/v1/accounts/)

User Management (Admin)

• DELETE /accounts/users/<user_id>/delete/ - Delete user while preserving submissions
• GET /accounts/users/<user_id>/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/<list_id>/ - Update top list
• DELETE /accounts/top-lists/<list_id>/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/<location_type>/<location_id>/ - 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/<park_slug>/ - Get park history
• GET /history/parks/<park_slug>/detail/ - Get detailed park history

Ride History

• GET /history/parks/<park_slug>/rides/<ride_slug>/ - Get ride history
• GET /history/parks/<park_slug>/rides/<ride_slug>/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/<ride_slug>/ - Get detailed ranking for specific ride
• GET /api/v1/rankings/<ride_slug>/history/ - Get ranking history for ride
• GET /api/v1/rankings/<ride_slug>/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/<id>/ - Get specific report details
• PUT /moderation/reports/<id>/ - Update moderation report
• PATCH /moderation/reports/<id>/ - Partial update report
• DELETE /moderation/reports/<id>/ - Delete moderation report
• POST /moderation/reports/<id>/assign/ - Assign report to moderator
• POST /moderation/reports/<id>/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/<id>/ - Get specific queue item
• PUT /moderation/queue/<id>/ - Update queue item
• PATCH /moderation/queue/<id>/ - Partial update queue item
• DELETE /moderation/queue/<id>/ - Delete queue item
• POST /moderation/queue/<id>/assign/ - Assign queue item to moderator
• POST /moderation/queue/<id>/unassign/ - Unassign queue item
• POST /moderation/queue/<id>/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/<id>/ - Get specific action details
• PUT /moderation/actions/<id>/ - Update moderation action
• PATCH /moderation/actions/<id>/ - Partial update action
• DELETE /moderation/actions/<id>/ - Delete moderation action
• POST /moderation/actions/<id>/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/<id>/ - Get bulk operation details
• PUT /moderation/bulk-operations/<id>/ - Update bulk operation
• PATCH /moderation/bulk-operations/<id>/ - Partial update operation
• DELETE /moderation/bulk-operations/<id>/ - Delete bulk operation
• POST /moderation/bulk-operations/<id>/cancel/ - Cancel bulk operation
• POST /moderation/bulk-operations/<id>/retry/ - Retry failed operation
• GET /moderation/bulk-operations/<id>/logs/ - Get operation logs
• GET /moderation/bulk-operations/running/ - Get running operations

User Moderation

• GET /moderation/users/<id>/ - Get user moderation profile
• POST /moderation/users/<id>/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/<manufacturer_slug>/)

Ride Models

• GET /rides/manufacturers/<manufacturer_slug>/ - List ride models by manufacturer
• POST /rides/manufacturers/<manufacturer_slug>/ - Create new ride model
• GET /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/ - Get ride model details
• PATCH /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/ - Update ride model
• DELETE /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/ - Delete ride model

Model Search & Filtering

• GET /rides/manufacturers/<manufacturer_slug>/search/ - Search ride models
• GET /rides/manufacturers/<manufacturer_slug>/filter-options/ - Get filter options
• GET /rides/manufacturers/<manufacturer_slug>/stats/ - Get manufacturer statistics

Model Variants

• GET /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/variants/ - List model variants
• POST /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/variants/ - Create variant
• GET /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/variants/<id>/ - Get variant details
• PATCH /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/variants/<id>/ - Update variant
• DELETE /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/variants/<id>/ - Delete variant

Technical Specifications

• GET /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/technical-specs/ - List technical specs
• POST /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/technical-specs/ - Create technical spec
• GET /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/technical-specs/<id>/ - Get spec details
• PATCH /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/technical-specs/<id>/ - Update spec
• DELETE /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/technical-specs/<id>/ - Delete spec

Model Photos

• GET /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/photos/ - List model photos
• POST /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/photos/ - Upload model photo
• GET /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/photos/<id>/ - Get photo details
• PATCH /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/photos/<id>/ - Update photo
• DELETE /rides/manufacturers/<manufacturer_slug>/<ride_model_slug>/photos/<id>/ - 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

headers: {
  'Authorization': 'Bearer <access_token>',
  'Content-Type': 'application/json'
}

Pagination Response

{
  "count": 100,
  "next": "http://api.example.com/api/v1/endpoint/?page=2",
  "previous": null,
  "results": [...]
}

Error Response Format

{
  "error": "Error message",
  "error_code": "SPECIFIC_ERROR_CODE",
  "details": {...},
  "suggestions": ["suggestion1", "suggestion2"]
}

Success Response Format

{
  "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

// 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

const parks = await fetch('/api/v1/parks/?continent=NA&min_rating=4.0&page=1', {
  headers: { 'Authorization': `Bearer ${access_token}` }
});

Upload Park Photo

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.