YeboCars Route Map

Complete API endpoint documentation for the YeboCars backend (80+ endpoints).

Route Overview

All routes are mounted from routes/index.ts:

// Core routes
router.use('/auth', authRoutes);
router.use('/cars', carRoutes);
router.use('/dealers', dealerRoutes);
router.use('/dealer-applications', dealerApplicationRoutes);
router.use('/customers', customerRoutes);

// AI & VIN
router.use('/ai', aiRoutes);
router.use('/vin', vinRoutes);

// Support
router.use('/media', mediaRoutes);
router.use('/countries', countryRoutes);
router.use('/messages', messageRoutes);
router.use('/notifications', notificationRoutes);

// Dashboard & Billing
router.use('/api/dashboard', dashboardRoutes);
router.use('/api/blog', blogRoutes);
router.use('/api/billing', billingRoutes);

---

Authentication Routes /auth

Method	Endpoint	Description	Auth
POST	/signup	Register new user	❌
POST	/login	Login with phone/password	❌
POST	/refresh	Refresh access token	🔒
POST	/logout	Logout user	🔒
POST	/verify-phone	Verify phone with OTP	❌
POST	/resend-otp	Resend verification OTP	❌
POST	/forgot-password	Request password reset	❌
POST	/reset-password	Reset password with OTP	❌
GET	/me	Get current user profile	🔒
PUT	/me	Update current user	🔒
DELETE	/me	Delete account	🔒

---

Car Routes /cars

Method	Endpoint	Description	Auth
POST	/	Create car listing	🔒
GET	/	List all cars	❌
GET	/feed	Get car feed	❌
GET	/search	Search cars	❌
GET	/featured	Get featured cars	❌
GET	/trending	Get trending cars	❌
GET	/recent	Get recent listings	❌
GET	/:carId	Get car by ID	❌
PUT	/:carId	Update car	🔒
DELETE	/:carId	Delete car	🔒
POST	/:carId/favorite	Favorite a car	🔒
DELETE	/:carId/favorite	Unfavorite a car	🔒
POST	/:carId/share	Share a car	🔒
GET	/:carId/similar	Get similar cars	❌
GET	/:carId/analytics	Get car analytics	🔒
POST	/:carId/inquiry	Send inquiry	🔒
POST	/:carId/test-drive	Request test drive	🔒
POST	/:carId/report	Report listing	🔒

Filter Options

// Query parameters for GET /cars
{
  make?: string;           // Filter by make (Toyota, Honda, etc.)
  model?: string;          // Filter by model
  minPrice?: number;       // Minimum price
  maxPrice?: number;       // Maximum price
  minYear?: number;        // Minimum year
  maxYear?: number;        // Maximum year
  fuelType?: string;       // Petrol, Diesel, Electric, Hybrid
  transmission?: string;   // Automatic, Manual
  bodyType?: string;       // Sedan, SUV, Hatchback, etc.
  maxMileage?: number;     // Maximum mileage
  sellerType?: string;     // dealer, private
  countryId?: string;      // Country filter
  condition?: string;      // new, used, certified
  page?: number;           // Page number
  limit?: number;          // Results per page
  sort?: string;           // price, year, mileage, createdAt
  order?: string;          // asc, desc
}

Reference Data

Method	Endpoint	Description
GET	/makes	Get all car makes
GET	/makes/:make/models	Get models for a make
GET	/body-types	Get all body types
GET	/features	Get common features
GET	/template	Get listing template

---

Dealer Routes /dealers

Method	Endpoint	Description	Auth
GET	/	List all dealers	❌
GET	/:dealerId	Get dealer by ID	❌
GET	/:dealerId/cars	Get dealer's cars	❌
GET	/:dealerId/reviews	Get dealer reviews	❌
GET	/:dealerId/stats	Get dealer statistics	🔒
PUT	/:dealerId	Update dealer profile	🔒
GET	/me	Get current dealer	🔒 Dealer
GET	/me/leads	Get my leads	🔒 Dealer
GET	/me/analytics	Get my analytics	🔒 Dealer
GET	/me/inventory	Get my inventory	🔒 Dealer
PUT	/me/settings	Update settings	🔒 Dealer

---

Dealer Application Routes /dealer-applications

Method	Endpoint	Description	Auth
POST	/	Submit application	🔒
GET	/	List all applications	🔒 Admin
GET	/my	Get my application	🔒
GET	/:applicationId	Get application details	🔒
PUT	/:applicationId/approve	Approve application	🔒 Admin
PUT	/:applicationId/reject	Reject application	🔒 Admin
PUT	/:applicationId/documents	Upload documents	🔒

---

Customer Routes /customers

Method	Endpoint	Description	Auth
GET	/me/favorites	Get my favorites	🔒
GET	/me/saved-searches	Get saved searches	🔒
POST	/me/saved-searches	Create saved search	🔒
DELETE	/me/saved-searches/:id	Delete saved search	🔒
GET	/me/inquiries	Get my inquiries	🔒
GET	/me/test-drives	Get my test drives	🔒
GET	/me/notifications	Get notifications	🔒
PUT	/me/preferences	Update preferences	🔒

---

AI Routes /ai

Method	Endpoint	Description	Auth
POST	/search	Natural language search	❌
POST	/generate-listing	Generate listing from data	🔒
POST	/enhance-description	Enhance description	🔒
POST	/recommendations	Get lifestyle recommendations	❌
GET	/pricing-insights/:carId	Get pricing insights	❌

Natural Language Search

POST /ai/search
Content-Type: application/json

{
  "query": "reliable family SUV under $30,000 good for long trips"
}

Response:
{
  "availableCars": [
    {
      "car": { "make": "Toyota", "model": "RAV4", "price": 28000 },
      "matchScore": 0.92,
      "reasons": ["Perfect body type: SUV", "Within budget"],
      "lifestyleMatch": "Great for family use with spacious interior"
    }
  ],
  "searchIntent": {
    "query": "reliable family SUV under $30,000",
    "extractedCriteria": {
      "bodyType": "suv",
      "priceRange": { "max": 30000 },
      "targetDemographic": "families"
    },
    "confidence": 0.85
  }
}

Lifestyle Recommendations

POST /ai/recommendations
Content-Type: application/json

{
  "familySize": "large-family",
  "commutingDistance": "long",
  "budget": { "min": 20000, "max": 50000 },
  "usage": "adventure",
  "fuelPreference": "Hybrid"
}

Response:
{
  "recommendations": [...],
  "explanation": "Based on your lifestyle...",
  "score": 0.85,
  "lifestyleSummary": {
    "primaryNeed": "Space for large family",
    "secondaryConsiderations": ["Fuel efficiency", "Durability"],
    "budgetCategory": "Mid-range"
  }
}

---

VIN Routes /vin

Method	Endpoint	Description	Auth
GET	/lookup/:vin	Lookup VIN	❌
POST	/decode	Decode VIN	❌
POST	/validate	Validate VIN format	❌

VIN Lookup

GET /vin/lookup/1HGBH41JXMN109186

Response:
{
  "success": true,
  "data": {
    "make": "Honda",
    "model": "Civic",
    "year": 2021,
    "bodyType": "Sedan",
    "fuelType": "Petrol",
    "transmission": "Automatic",
    "engine": "2.0L 4-Cylinder",
    "trim": "LX",
    "features": ["Air Conditioning", "Power Steering", "ABS", "Airbags"]
  }
}

---

Media Routes /media

Method	Endpoint	Description	Auth
POST	/upload	Upload media file	🔒
POST	/upload-multiple	Upload multiple files	🔒
DELETE	/:mediaId	Delete media	🔒
GET	/signed-url	Get signed upload URL	🔒

---

Country Routes /countries

Method	Endpoint	Description	Auth
GET	/	List all countries	❌
GET	/supported	List supported countries	❌
GET	/:countryId	Get country by ID	❌
GET	/code/:code	Get country by code	❌
GET	/:countryId/currency	Get country currency	❌

---

Message Routes /messages

Method	Endpoint	Description	Auth
GET	/	Get all conversations	🔒
GET	/:conversationId	Get conversation	🔒
POST	/	Send message	🔒
PUT	/:messageId/read	Mark as read	🔒
DELETE	/:messageId	Delete message	🔒

---

Notification Routes /notifications

Method	Endpoint	Description	Auth
GET	/	Get notifications	🔒
GET	/unread-count	Get unread count	🔒
PUT	/:id/read	Mark as read	🔒
PUT	/read-all	Mark all as read	🔒
DELETE	/:id	Delete notification	🔒
PUT	/settings	Update notification settings	🔒

---

Billing Routes /api/billing

Method	Endpoint	Description	Auth
GET	/plans	Get subscription plans	❌
POST	/checkout	Create checkout session	🔒 Dealer
POST	/webhook	Stripe webhook	Stripe
GET	/subscription	Get current subscription	🔒 Dealer
POST	/cancel	Cancel subscription	🔒 Dealer
GET	/invoices	Get invoices	🔒 Dealer
GET	/usage	Get usage stats	🔒 Dealer

Get Plans

GET /api/billing/plans?countryCode=ZA

Response:
{
  "plans": [
    {
      "id": "BASIC",
      "name": "Basic",
      "priceUsdCents": 1000,
      "displayCurrency": "ZAR",
      "displayAmount": 18500,
      "displayFormatted": "R185.00",
      "features": ["10 car listings", "Basic analytics"],
      "listingLimit": 10
    },
    {
      "id": "DEALER",
      "name": "Dealer",
      "priceUsdCents": 2500,
      "displayCurrency": "ZAR",
      "displayAmount": 46250,
      "displayFormatted": "R462.50",
      "features": ["50 car listings", "Lead management", "Featured slots"],
      "listingLimit": 50
    },
    {
      "id": "PRO",
      "name": "Pro",
      "priceUsdCents": 6000,
      "displayCurrency": "ZAR",
      "displayAmount": 111000,
      "displayFormatted": "R1,110.00",
      "features": ["Unlimited listings", "Priority placement", "Account manager"],
      "listingLimit": -1
    }
  ]
}

---

Dashboard Routes /api/dashboard

Method	Endpoint	Description	Auth
GET	/metrics	Get platform metrics	API Key
GET	/analytics	Get analytics data	API Key
GET	/users	Get user stats	API Key
GET	/cars	Get car stats	API Key
GET	/revenue	Get revenue data	API Key

---

Blog Routes /api/blog

Method	Endpoint	Description	Auth
GET	/posts	Get blog posts	❌
GET	/posts/:slug	Get post by slug	❌
POST	/posts	Create post	API Key
PUT	/posts/:id	Update post	API Key
DELETE	/posts/:id	Delete post	API Key
GET	/categories	Get categories	❌

---

Admin Routes

Method	Endpoint	Description	Auth
GET	/admin/users	List all users	🔒 Admin
GET	/admin/dealers	List all dealers	🔒 Admin
GET	/admin/cars	List all cars	🔒 Admin
GET	/admin/reports	List reports	🔒 Admin
PUT	/admin/cars/:id/approve	Approve car	🔒 Admin
PUT	/admin/cars/:id/reject	Reject car	🔒 Admin
PUT	/admin/users/:id/ban	Ban user	🔒 Admin

---

Health Check

GET /health

Response:
{
  "success": true,
  "message": "Bamzu Car Marketplace API is running",
  "version": "1.0.0",
  "timestamp": "2024-03-15T10:30:00Z",
  "endpoints": {
    "auth": "/auth",
    "cars": "/cars",
    "dealers": "/dealers",
    "ai": "/ai",
    "vin": "/vin",
    "billing": "/api/billing"
  }
}