YeboCars API Reference

Complete API documentation for the YeboCars Car Marketplace platform.

Base URLs

Production: https://api.yebocars.app
Development: https://dev-api.yebocars.app
Local: http://localhost:6792

Authentication

YeboCars uses JWT Bearer token authentication.

Authentication Header

http

Authorization: Bearer YOUR_ACCESS_TOKEN

Token Types

Token Type	Lifetime	Usage
Access Token	24 hours	API requests
Refresh Token	30 days	Token renewal

Authentication Endpoints

Create a new user account. All users start as regular users.

http

POST /auth/signup

cURLNode.jsPythonPHP

bash

curl -X POST https://api.yebocars.app/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+26878422613",
    "email": "user@example.com",
    "password": "password123",
    "name": "John Doe"
  }'

javascript

const response = await fetch('https://api.yebocars.app/auth/signup', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phone: '+26878422613',
    email: 'user@example.com',
    password: 'password123',
    name: 'John Doe'
  })
});

const data = await response.json();

python

import requests

response = requests.post(
    'https://api.yebocars.app/auth/signup',
    json={
        'phone': '+26878422613',
        'email': 'user@example.com',
        'password': 'password123',
        'name': 'John Doe'
    }
)

print(response.json())

php

<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.yebocars.app/auth/signup',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'phone' => '+26878422613',
        'email' => 'user@example.com',
        'password' => 'password123',
        'name' => 'John Doe'
    ])
]);

$response = curl_exec($curl);
$data = json_decode($response, true);

curl_close($curl);
?>

Response

json

{
  "success": true,
  "message": "Verification code sent successfully",
  "data": {
    "user": {
      "_id": "507f1f77bcf86cd799439011",
      "phone": "+26878422613",
      "email": "user@example.com",
      "name": "John Doe",
      "role": "user",
      "isPhoneVerified": false
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Parameters

Parameter	Type	Required	Description
`phone`	string	Yes	Phone number in international format (E.164)
`email`	string	No	Valid email address
`password`	string	Yes	Password (minimum 6 characters)
`name`	string	No	User's full name

Complete registration by verifying the OTP sent to the phone number.

http

POST /auth/verify-signup

cURLNode.jsPython

bash

curl -X POST https://api.yebocars.app/auth/verify-signup \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+26878422613",
    "otp": "123456"
  }'

javascript

const response = await fetch('https://api.yebocars.app/auth/verify-signup', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phone: '+26878422613',
    otp: '123456'
  })
});

const data = await response.json();

python

import requests

response = requests.post(
    'https://api.yebocars.app/auth/verify-signup',
    json={
        'phone': '+26878422613',
        'otp': '123456'
    }
)

print(response.json())

Response

json

{
  "success": true,
  "message": "Registration completed successfully",
  "data": {
    "user": {
      "_id": "507f1f77bcf86cd799439011",
      "phone": "+26878422613",
      "email": "user@example.com",
      "name": "John Doe",
      "role": "user",
      "isPhoneVerified": true
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Authenticate a user and receive access tokens.

http

POST /auth/login

cURLNode.jsPython

bash

curl -X POST https://api.yebocars.app/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+26878422613",
    "password": "password123"
  }'

javascript

const response = await fetch('https://api.yebocars.app/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phone: '+26878422613',
    password: 'password123'
  })
});

const data = await response.json();

python

import requests

response = requests.post(
    'https://api.yebocars.app/auth/login',
    json={
        'phone': '+26878422613',
        'password': 'password123'
    }
)

print(response.json())

Response

json

{
  "success": true,
  "message": "Login successful",
  "data": {
    "user": {
      "_id": "507f1f77bcf86cd799439011",
      "phone": "+26878422613",
      "email": "user@example.com",
      "name": "John Doe",
      "role": "user"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Refresh Token

Generate a new access token using a valid refresh token.

http

POST /auth/refresh-token

cURLNode.js

bash

curl -X POST https://api.yebocars.app/auth/refresh-token \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

javascript

const response = await fetch('https://api.yebocars.app/auth/refresh-token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    refreshToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
  })
});

const data = await response.json();

Response

json

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Get Current User

Retrieve the currently authenticated user's profile.

http

GET /auth/me

cURLNode.jsPython

bash

curl -X GET https://api.yebocars.app/auth/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

javascript

const response = await fetch('https://api.yebocars.app/auth/me', {
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  }
});

const data = await response.json();

python

import requests

response = requests.get(
    'https://api.yebocars.app/auth/me',
    headers={
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
    }
)

print(response.json())

Forgot Password

Request a password reset OTP.

http

POST /auth/forgot-password

Request Body

json

{
  "phone": "+26878422613"
}

Verify Forgot Password

Verify the OTP and receive a temporary reset token.

http

POST /auth/verify-forgot-password

Request Body

json

{
  "phone": "+26878422613",
  "otp": "123456"
}

Reset Password

Reset password using the temporary token from OTP verification.

http

POST /auth/reset-password

Request Body

json

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "newPassword": "newpassword123"
}

Resend OTP

Resend verification code for signup or password reset.

http

POST /auth/resend-otp

Request Body

json

{
  "phone": "+26878422613",
  "type": "signup"
}

Parameters

Parameter	Type	Required	Description
`phone`	string	Yes	Phone number in international format
`type`	string	Yes	Type of OTP: `signup` or `password_reset`

Get Dealer Application Status

Check the current user's dealer application status.

http

GET /auth/dealer-application-status

Response

json

{
  "success": true,
  "data": {
    "hasApplication": true,
    "applicationStatus": "pending",
    "isDealer": false,
    "canApply": false,
    "application": {
      "businessName": "Premium Auto Sales",
      "status": "pending",
      "submittedAt": "2025-01-15T10:00:00Z"
    }
  }
}

Car Endpoints

Get All Cars

Retrieve a paginated list of car listings with optional filtering.

http

GET /cars?page=1&limit=10&make=Toyota&minPrice=10000&maxPrice=50000

cURLNode.jsPython

bash

curl -X GET "https://api.yebocars.app/cars?page=1&limit=10&make=Toyota" \
  -H "Content-Type: application/json"

javascript

const params = new URLSearchParams({
  page: '1',
  limit: '10',
  make: 'Toyota',
  minPrice: '10000',
  maxPrice: '50000'
});

const response = await fetch(`https://api.yebocars.app/cars?${params}`);
const data = await response.json();

python

import requests

params = {
    'page': 1,
    'limit': 10,
    'make': 'Toyota',
    'minPrice': 10000,
    'maxPrice': 50000
}

response = requests.get('https://api.yebocars.app/cars', params=params)
print(response.json())

Query Parameters

Parameter	Type	Description
`make`	string	Filter by car make
`model`	string	Filter by car model
`minPrice`	number	Minimum price filter
`maxPrice`	number	Maximum price filter
`minYear`	integer	Minimum year filter
`maxYear`	integer	Maximum year filter
`fuelType`	string	Filter by fuel type: `Petrol`, `Diesel`, `Electric`, `Hybrid`
`transmission`	string	Filter by transmission: `Manual`, `Automatic`
`bodyType`	string	Filter by body type
`maxMileage`	integer	Maximum mileage filter
`sellerType`	string	Filter by seller: `dealer`, `private`
`status`	string	Filter by status: `active`, `sold`, `reserved`
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 10)
`sort`	string	Sort criteria (e.g., `price:asc`, `year:desc`)

Response

json

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "make": "Toyota",
      "model": "Camry",
      "year": 2022,
      "price": 25000,
      "mileage": 15000,
      "fuelType": "Petrol",
      "transmission": "Automatic",
      "bodyType": "Sedan",
      "color": "White",
      "description": "Well-maintained Toyota Camry in excellent condition",
      "images": [
        "https://cdn.yebocars.app/cars/image1.jpg",
        "https://cdn.yebocars.app/cars/image2.jpg"
      ],
      "features": ["Air Conditioning", "Bluetooth", "Backup Camera"],
      "condition": "Used",
      "status": "active",
      "sellerId": "507f1f77bcf86cd799439012",
      "sellerType": "dealer",
      "createdAt": "2025-01-10T08:00:00Z",
      "updatedAt": "2025-01-10T08:00:00Z"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 5,
    "totalItems": 48,
    "itemsPerPage": 10
  }
}

Get Car by ID

Retrieve a specific car listing by its ID.

http

GET /cars/{id}

cURLNode.jsPython

bash

curl -X GET https://api.yebocars.app/cars/507f1f77bcf86cd799439011 \
  -H "Content-Type: application/json"

javascript

const carId = '507f1f77bcf86cd799439011';
const response = await fetch(`https://api.yebocars.app/cars/${carId}`);
const data = await response.json();

python

import requests

car_id = '507f1f77bcf86cd799439011'
response = requests.get(f'https://api.yebocars.app/cars/{car_id}')
print(response.json())

Create Car Listing

Create a new car listing (authenticated users only).

http

POST /cars

cURLNode.jsPython

bash

curl -X POST https://api.yebocars.app/cars \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "make": "Toyota",
    "model": "Camry",
    "year": 2022,
    "price": 25000,
    "mileage": 15000,
    "fuelType": "Petrol",
    "transmission": "Automatic",
    "bodyType": "Sedan",
    "color": "White",
    "description": "Well-maintained Toyota Camry",
    "images": ["https://cdn.example.com/image1.jpg"],
    "features": ["Air Conditioning", "Bluetooth"],
    "condition": "Used"
  }'

javascript

const response = await fetch('https://api.yebocars.app/cars', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  },
  body: JSON.stringify({
    make: 'Toyota',
    model: 'Camry',
    year: 2022,
    price: 25000,
    mileage: 15000,
    fuelType: 'Petrol',
    transmission: 'Automatic',
    bodyType: 'Sedan',
    color: 'White',
    description: 'Well-maintained Toyota Camry',
    images: ['https://cdn.example.com/image1.jpg'],
    features: ['Air Conditioning', 'Bluetooth'],
    condition: 'Used'
  })
});

const data = await response.json();

python

import requests

response = requests.post(
    'https://api.yebocars.app/cars',
    headers={
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
    },
    json={
        'make': 'Toyota',
        'model': 'Camry',
        'year': 2022,
        'price': 25000,
        'mileage': 15000,
        'fuelType': 'Petrol',
        'transmission': 'Automatic',
        'bodyType': 'Sedan',
        'color': 'White',
        'description': 'Well-maintained Toyota Camry',
        'images': ['https://cdn.example.com/image1.jpg'],
        'features': ['Air Conditioning', 'Bluetooth'],
        'condition': 'Used'
    }
)

print(response.json())

Required Fields

Field	Type	Description
`make`	string	Car make
`model`	string	Car model
`year`	integer	Manufacturing year (1900-2026)
`mileage`	integer	Mileage in kilometers
`fuelType`	string	`Petrol`, `Diesel`, `Electric`, or `Hybrid`
`transmission`	string	`Manual` or `Automatic`
`bodyType`	string	Body type (e.g., Sedan, SUV)
`color`	string	Exterior color
`description`	string	Car description
`condition`	string	`New`, `Used`, or `Certified Pre-Owned`

Optional Fields

Field	Type	Description
`price`	number	Price (defaults to 0 if not provided)
`images`	array	Array of image URLs (max 20)
`videos`	array	Array of video URLs (max 10)
`features`	array	Array of feature strings (max 50)
`status`	string	`active`, `sold`, or `reserved` (default: active)

Update Car Listing

Update an existing car listing (owner/admin only).

http

PUT /cars/{id}

cURLNode.js

bash

curl -X PUT https://api.yebocars.app/cars/507f1f77bcf86cd799439011 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "price": 24000,
    "status": "active"
  }'

javascript

const carId = '507f1f77bcf86cd799439011';
const response = await fetch(`https://api.yebocars.app/cars/${carId}`, {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  },
  body: JSON.stringify({
    price: 24000,
    status: 'active'
  })
});

const data = await response.json();

Delete Car Listing

Delete a car listing (owner/admin only).

http

DELETE /cars/{id}

cURLNode.js

bash

curl -X DELETE https://api.yebocars.app/cars/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

javascript

const carId = '507f1f77bcf86cd799439011';
const response = await fetch(`https://api.yebocars.app/cars/${carId}`, {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  }
});

const data = await response.json();

Get My Cars

Get all car listings belonging to the authenticated user.

http

GET /cars/my-cars?status=active&page=1&limit=10

cURLNode.js

bash

curl -X GET "https://api.yebocars.app/cars/my-cars?status=active" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

javascript

const params = new URLSearchParams({
  status: 'active',
  page: '1',
  limit: '10'
});

const response = await fetch(`https://api.yebocars.app/cars/my-cars?${params}`, {
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  }
});

const data = await response.json();

Advanced Car Search

Perform advanced search with complex filters including location.

http

POST /cars/advanced-search

cURLNode.js

bash

curl -X POST https://api.yebocars.app/cars/advanced-search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "toyota camry",
    "filters": {
      "minPrice": 10000,
      "maxPrice": 30000,
      "minYear": 2018,
      "transmission": "Automatic"
    },
    "sortBy": "price:asc",
    "page": 1,
    "limit": 10
  }'

javascript

const response = await fetch('https://api.yebocars.app/cars/advanced-search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'toyota camry',
    filters: {
      minPrice: 10000,
      maxPrice: 30000,
      minYear: 2018,
      transmission: 'Automatic'
    },
    sortBy: 'price:asc',
    page: 1,
    limit: 10
  })
});

const data = await response.json();

Get Car Analytics

Get analytics for a specific car (owner only).

http

GET /cars/{id}/analytics

Response

json

{
  "success": true,
  "data": {
    "views": 245,
    "inquiries": 12,
    "favorites": 8,
    "viewHistory": [
      {
        "date": "2025-01-10",
        "count": 35
      },
      {
        "date": "2025-01-11",
        "count": 42
      }
    ]
  }
}

Car Interaction Endpoints

Like a Car

http

POST /cars/{id}/like

Get Car Views

http

GET /cars/{id}/views

Increment Car Views

http

POST /cars/{id}/views

Get Car Comments

http

GET /cars/{id}/comments

Post Car Comment

http

POST /cars/{id}/comments

Request Body

json

{
  "text": "Is this car still available?",
  "rating": 5
}

http

POST /cars/{id}/share

Schedule Test Drive

http

POST /cars/{id}/test-drive

Request Body

json

{
  "preferredDate": "2025-01-20",
  "preferredTime": "10:00 AM",
  "message": "I'd like to schedule a test drive"
}

Get currently trending car listings.

http

GET /cars/trending

Car Data Endpoints

Get All Makes

http

GET /cars/makes

Response

json

{
  "success": true,
  "data": ["Toyota", "Honda", "BMW", "Mercedes-Benz", "Ford"]
}

Get Models by Make

http

GET /cars/models/{make}

Response

json

{
  "success": true,
  "data": ["Camry", "Corolla", "Prius", "RAV4", "Highlander"]
}

Get Body Types

http

GET /cars/body-types

Response

json

{
  "success": true,
  "data": ["Sedan", "SUV", "Hatchback", "Coupe", "Convertible", "Pickup"]
}

Get Features

http

GET /cars/features

Response

json

{
  "success": true,
  "data": [
    "Air Conditioning",
    "Bluetooth",
    "Backup Camera",
    "Sunroof",
    "Leather Seats",
    "Navigation System"
  ]
}

Get Car Template

Get suggested features and specs for a specific make/model.

http

GET /cars/templates/{make}/{model}

Response

json

{
  "success": true,
  "data": {
    "suggestedFeatures": [
      "Air Conditioning",
      "Bluetooth",
      "Backup Camera"
    ],
    "averagePrice": 22000,
    "commonSpecs": {
      "fuelType": "Petrol",
      "transmission": "Automatic",
      "bodyType": "Sedan"
    }
  }
}

Get User's Liked Cars

http

GET /cars/user/liked

Get Batch Car Stats

Get statistics for multiple cars at once.

http

POST /cars/stats/batch

Request Body

json

{
  "carIds": [
    "507f1f77bcf86cd799439011",
    "507f1f77bcf86cd799439012"
  ]
}

Comment Interactions

Like a Comment

http

POST /cars/comments/{commentId}/like

Reply to Comment

http

POST /cars/comments/{commentId}/reply

Request Body

json

{
  "text": "Yes, it's still available!"
}

AI Endpoints

YeboCars's AI-powered features using Google Gemini AI.

Generate Car Listing

Generate a complete car listing description using AI (dealers only).

http

POST /ai/generate-listing

cURLNode.js

bash

curl -X POST https://api.yebocars.app/ai/generate-listing \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "make": "Toyota",
    "model": "Camry",
    "year": 2022,
    "mileage": 15000,
    "condition": "Used",
    "features": ["Air Conditioning", "Bluetooth"]
  }'

javascript

const response = await fetch('https://api.yebocars.app/ai/generate-listing', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  },
  body: JSON.stringify({
    make: 'Toyota',
    model: 'Camry',
    year: 2022,
    mileage: 15000,
    condition: 'Used',
    features: ['Air Conditioning', 'Bluetooth']
  })
});

const data = await response.json();

Response

json

{
  "success": true,
  "data": {
    "description": "This well-maintained 2022 Toyota Camry is the perfect blend of reliability and style. With only 15,000km on the odometer, this sedan is barely broken in and ready for many more miles of dependable service...",
    "highlights": [
      "Low mileage vehicle",
      "Air Conditioning for comfort",
      "Bluetooth connectivity"
    ]
  }
}

Enhance Description

Enhance an existing car listing description (dealers only).

http

POST /ai/enhance-description

cURLNode.js

bash

curl -X POST https://api.yebocars.app/ai/enhance-description \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "description": "Good car, low mileage",
    "make": "Toyota",
    "model": "Camry",
    "year": 2022
  }'

javascript

const response = await fetch('https://api.yebocars.app/ai/enhance-description', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  },
  body: JSON.stringify({
    description: 'Good car, low mileage',
    make: 'Toyota',
    model: 'Camry',
    year: 2022
  })
});

const data = await response.json();

Natural Language Search

Search for cars using natural language queries.

http

POST /ai/search-natural-language

cURLNode.jsPython

bash

curl -X POST https://api.yebocars.app/ai/search-natural-language \
  -H "Content-Type: application/json" \
  -d '{
    "query": "I need a reliable SUV under $20,000 with good fuel economy"
  }'

javascript

const response = await fetch('https://api.yebocars.app/ai/search-natural-language', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'I need a reliable SUV under $20,000 with good fuel economy'
  })
});

const data = await response.json();

python

import requests

response = requests.post(
    'https://api.yebocars.app/ai/search-natural-language',
    json={
        'query': 'I need a reliable SUV under $20,000 with good fuel economy'
    }
)

print(response.json())

Response

json

{
  "success": true,
  "data": {
    "interpretedQuery": {
      "bodyType": "SUV",
      "maxPrice": 20000,
      "priorityFeatures": ["fuel economy", "reliability"]
    },
    "results": [
      {
        "_id": "507f1f77bcf86cd799439011",
        "make": "Toyota",
        "model": "RAV4",
        "year": 2019,
        "price": 18500,
        "fuelType": "Hybrid"
      }
    ]
  }
}

Get AI Recommendations

Get personalized car recommendations based on user preferences.

http

POST /ai/recommendations

cURLNode.js

bash

curl -X POST https://api.yebocars.app/ai/recommendations \
  -H "Content-Type: application/json" \
  -d '{
    "budget": 25000,
    "preferences": {
      "fuelType": "Petrol",
      "transmission": "Automatic",
      "bodyType": "Sedan"
    },
    "lifestyle": "family"
  }'

javascript

const response = await fetch('https://api.yebocars.app/ai/recommendations', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    budget: 25000,
    preferences: {
      fuelType: 'Petrol',
      transmission: 'Automatic',
      bodyType: 'Sedan'
    },
    lifestyle: 'family'
  })
});

const data = await response.json();

Get Pricing Insights

Get AI-powered pricing insights and market analysis for a specific car.

http

POST /ai/pricing-insights

cURLNode.js

bash

curl -X POST https://api.yebocars.app/ai/pricing-insights \
  -H "Content-Type: application/json" \
  -d '{
    "carId": "507f1f77bcf86cd799439011"
  }'

javascript

const response = await fetch('https://api.yebocars.app/ai/pricing-insights', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    carId: '507f1f77bcf86cd799439011'
  })
});

const data = await response.json();

Response

json

{
  "success": true,
  "data": {
    "currentPrice": 25000,
    "marketAverage": 24500,
    "priceAnalysis": "fairly priced",
    "similarCars": [
      {
        "make": "Honda",
        "model": "Accord",
        "year": 2022,
        "price": 24800
      }
    ],
    "recommendation": "This car is priced competitively for the market. Similar vehicles are listed between $23,500 and $26,000."
  }
}

Generate Car Description

Generate a compelling car description based on specifications.

http

POST /ai/generate-car-description

cURLNode.js

bash

curl -X POST https://api.yebocars.app/ai/generate-car-description \
  -H "Content-Type: application/json" \
  -d '{
    "make": "Toyota",
    "model": "Camry",
    "year": 2020,
    "price": 25000,
    "mileage": 45000,
    "fuelType": "Petrol",
    "transmission": "Automatic",
    "bodyType": "Sedan",
    "exteriorColor": "White",
    "interiorColor": "Black",
    "condition": "Used",
    "features": ["Air Conditioning", "Power Steering", "Bluetooth"]
  }'

javascript

const response = await fetch('https://api.yebocars.app/ai/generate-car-description', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    make: 'Toyota',
    model: 'Camry',
    year: 2020,
    price: 25000,
    mileage: 45000,
    fuelType: 'Petrol',
    transmission: 'Automatic',
    bodyType: 'Sedan',
    exteriorColor: 'White',
    interiorColor: 'Black',
    condition: 'Used',
    features: ['Air Conditioning', 'Power Steering', 'Bluetooth']
  })
});

const data = await response.json();

Lifestyle Recommendations

Get car recommendations based on lifestyle quiz results.

http

POST /ai/lifestyle-recommendations

Dealer Endpoints

Get All Dealers

Retrieve a paginated list of dealers.

http

GET /dealers?type=dealer&isApproved=true&page=1&limit=10

cURLNode.js

bash

curl -X GET "https://api.yebocars.app/dealers?type=dealer&isApproved=true" \
  -H "Content-Type: application/json"

javascript

const params = new URLSearchParams({
  type: 'dealer',
  isApproved: 'true',
  page: '1',
  limit: '10'
});

const response = await fetch(`https://api.yebocars.app/dealers?${params}`);
const data = await response.json();

Response

json

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439012",
      "name": "Premium Auto Sales",
      "email": "contact@premiumauto.com",
      "phone": "+26878422613",
      "location": "Gaborone, Botswana",
      "type": "dealer",
      "isApproved": true,
      "rating": 4.5,
      "totalSales": 150,
      "joinedDate": "2024-06-01T00:00:00Z",
      "businessHours": {
        "monday": "9:00 AM - 6:00 PM",
        "tuesday": "9:00 AM - 6:00 PM"
      },
      "website": "https://premiumauto.com",
      "description": "Premium car dealership serving Botswana for over 10 years"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 3,
    "totalItems": 25,
    "itemsPerPage": 10
  }
}

Get Dealer by ID

http

GET /dealers/{id}

Get Dealer Cars

Get all cars listed by a specific dealer.

http

GET /dealers/{id}/cars?page=1&limit=10

Approve Dealer (Admin Only)

http

PUT /dealers/{id}/approve

Get Pending Dealers (Admin Only)

http

GET /dealers/admin/pending?page=1&limit=10

Get Dealer Profile

Get the currently authenticated dealer's profile.

http

GET /dealers/profile/me

Update Dealer Profile

Update the dealer's profile information.

http

PUT /dealers/profile/me

Request Body

json

{
  "name": "Premium Auto Sales Ltd",
  "location": "Gaborone, Botswana",
  "description": "Leading car dealership in Botswana"
}

Get Business Hours

http

GET /dealers/profile/business-hours

Update Business Hours

http

PUT /dealers/profile/business-hours

Request Body

json

{
  "businessHours": {
    "monday": "9:00 AM - 6:00 PM",
    "tuesday": "9:00 AM - 6:00 PM",
    "wednesday": "9:00 AM - 6:00 PM",
    "thursday": "9:00 AM - 6:00 PM",
    "friday": "9:00 AM - 6:00 PM",
    "saturday": "9:00 AM - 4:00 PM",
    "sunday": "Closed"
  }
}

Update Business Info

http

PUT /dealers/profile/business-info

Request Body

json

{
  "website": "https://example-dealership.com",
  "description": "Premium car dealership serving the community for over 20 years",
  "businessPhone": "+26878422613"
}

Get Dealer Statistics

Get comprehensive statistics for the dealer dashboard.

http

GET /dealers/stats

Response

json

{
  "success": true,
  "data": {
    "totalCars": 42,
    "totalViews": 3450,
    "totalInquiries": 128,
    "salesThisMonth": 8,
    "revenueThisMonth": 240000
  }
}

Export Cars

Export the dealer's car listings to CSV or JSON.

http

GET /dealers/export/cars?format=csv&status=active

Query Parameters

Parameter	Type	Description
`format`	string	Export format: `csv` or `json` (default: csv)
`dateFrom`	string	Start date (YYYY-MM-DD)
`dateTo`	string	End date (YYYY-MM-DD)
`status`	string	Filter by status: `active`, `sold`, `reserved`

Get Dealer Reviews

http

GET /dealers/{id}/reviews

Submit Dealer Review

http

POST /dealers/{id}/reviews

Request Body

json

{
  "rating": 5,
  "comment": "Excellent service and great selection of cars!"
}

Customer Endpoints

Get Favorites

Get the customer's favorite cars.

http

GET /customers/favorites

Add to Favorites

http

POST /customers/favorites/{carId}

Remove from Favorites

http

DELETE /customers/favorites/{carId}

Send Inquiry

Send an inquiry to a dealer about a specific car.

http

POST /customers/inquiries

cURLNode.js

bash

curl -X POST https://api.yebocars.app/customers/inquiries \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "carId": "507f1f77bcf86cd799439011",
    "dealerId": "507f1f77bcf86cd799439012",
    "message": "I am interested in this car. Is it still available?",
    "contactMethod": "whatsapp"
  }'

javascript

const response = await fetch('https://api.yebocars.app/customers/inquiries', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  },
  body: JSON.stringify({
    carId: '507f1f77bcf86cd799439011',
    dealerId: '507f1f77bcf86cd799439012',
    message: 'I am interested in this car. Is it still available?',
    contactMethod: 'whatsapp'
  })
});

const data = await response.json();

Parameters

Parameter	Type	Required	Description
`carId`	string	Yes	ID of the car
`dealerId`	string	Yes	ID of the dealer
`message`	string	Yes	Inquiry message (10-1000 characters)
`contactMethod`	string	Yes	Preferred contact: `whatsapp`, `phone`, or `email`

Get Inquiry History

http

GET /customers/inquiries?page=1&limit=10

Get Viewed Cars History

http

GET /customers/history/viewed-cars

Get Liked Cars

http

GET /customers/liked-cars

Message Endpoints

Real-time messaging between customers and dealers.

Send Message

http

POST /messages/send

Request Body

json

{
  "receiverId": "507f1f77bcf86cd799439012",
  "message": "Hello, is the Toyota Camry still available?"
}

Get Conversations

Get all conversations for the authenticated user.

http

GET /messages/conversations

Response

json

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439013",
      "participant": {
        "_id": "507f1f77bcf86cd799439012",
        "name": "Premium Auto Sales",
        "avatar": "https://cdn.yebocars.app/avatars/dealer.jpg"
      },
      "lastMessage": {
        "text": "Yes, it's still available!",
        "timestamp": "2025-01-15T14:30:00Z",
        "isRead": false
      },
      "unreadCount": 2
    }
  ]
}

Get Messages in Conversation

http

GET /messages/conversations/{receiverId}

Mark Message as Read

http

PUT /messages/{messageId}/read

Get Unread Count

http

GET /messages/unread-count

Response

json

{
  "success": true,
  "data": {
    "unreadCount": 5
  }
}

Get Conversation Unread Count

http

GET /messages/conversations/{participantId}/unread-count

Mark Conversation as Read

http

PUT /messages/conversations/{participantId}/read

VIN Lookup Endpoints

VIN Lookup

Retrieve vehicle information based on VIN (dealers only).

http

GET /vin/lookup/{vin}

cURLNode.jsPython

bash

curl -X GET https://api.yebocars.app/vin/lookup/1HGBH41JXMN109186 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

javascript

const vin = '1HGBH41JXMN109186';
const response = await fetch(`https://api.yebocars.app/vin/lookup/${vin}`, {
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  }
});

const data = await response.json();

python

import requests

vin = '1HGBH41JXMN109186'
response = requests.get(
    f'https://api.yebocars.app/vin/lookup/{vin}',
    headers={
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
    }
)

print(response.json())

Response

json

{
  "success": true,
  "data": {
    "vin": "1HGBH41JXMN109186",
    "make": "Honda",
    "model": "Accord",
    "year": 2021,
    "bodyType": "Sedan",
    "engineType": "2.0L I4",
    "transmission": "Automatic",
    "fuelType": "Petrol",
    "manufacturer": "Honda Motor Company"
  }
}

Error Responses

All API endpoints return errors in a consistent format.

Error Format

json

{
  "success": false,
  "error": "error_code",
  "message": "Human-readable error message"
}

Common HTTP Status Codes

Status Code	Description
200	Success
201	Created
400	Bad Request - Validation errors
401	Unauthorized - Invalid or missing token
403	Forbidden - Insufficient permissions
404	Not Found - Resource does not exist
409	Conflict - Resource already exists
422	Unprocessable Entity - Invalid data
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Error Examples

Validation Error

json

{
  "success": false,
  "error": "validation_error",
  "message": "Phone number must be in international format",
  "details": {
    "field": "phone",
    "value": "12345"
  }
}

Authentication Error

json

{
  "success": false,
  "error": "invalid_token",
  "message": "Access token is invalid or expired"
}

Not Found Error

json

{
  "success": false,
  "error": "car_not_found",
  "message": "Car with the specified ID does not exist"
}

Rate Limit Error

json

{
  "success": false,
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please try again in 60 seconds.",
  "retryAfter": 60
}

Rate Limiting

YeboCars implements rate limiting to ensure fair usage of the API.

Limits

Endpoint Type	Limit	Window
General	100 requests	15 minutes
Authentication	5 requests	15 minutes
Car Likes	50 requests	15 minutes
Comments	20 requests	15 minutes
Views	100 requests	15 minutes

Rate Limit Headers

Response headers include rate limit information:

http

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642521600

Pagination

All list endpoints support pagination.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	10	Items per page (max: 100)

Pagination Response

json

{
  "success": true,
  "data": [...],
  "pagination": {
    "currentPage": 1,
    "totalPages": 5,
    "totalItems": 48,
    "itemsPerPage": 10,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

WebSocket Events

YeboCars uses Socket.io for real-time features.

Connection

javascript

const socket = io('wss://api.yebocars.app', {
  auth: {
    token: 'YOUR_ACCESS_TOKEN'
  }
});

Events

New Message

javascript

socket.on('new_message', (data) => {
  console.log('New message:', data);
  // { senderId, message, timestamp }
});

Message Read

javascript

socket.on('message_read', (data) => {
  console.log('Message read:', data);
  // { messageId, readAt }
});

Car View Notification (Dealers)

javascript

socket.on('car_viewed', (data) => {
  console.log('Your car was viewed:', data);
  // { carId, viewCount }
});

New Inquiry (Dealers)

javascript

socket.on('new_inquiry', (data) => {
  console.log('New inquiry received:', data);
  // { inquiryId, carId, customerId, message }
});

Versioning

The YeboCars API is currently at version 1. Future breaking changes will be released under new versions (v2, v3, etc.).

Version Header

While not currently required, you can specify the API version:

http

Accept: application/vnd.yebocars.v1+json

Testing

Test Accounts

For development and testing, use these test accounts:

Test Customer

Phone: +26878422613
Password: test123

Test Dealer

Phone: +26878422614
Password: test123

Test Mode

All API requests to the development environment (dev-api.yebocars.app) run in test mode and do not affect production data.

Support

For API support, contact:

Email: api@yebocars.app
Documentation: https://docs.yebocars.app
Status Page: https://status.yebocars.app

API

Backend API

Okia AI Service

Frontend

Student Dashboard

Teacher Dashboard

Parent Dashboard

School Admin Dashboard

YeboCars API Reference ​

Base URLs ​

Authentication ​

Authentication Header ​

Token Types ​

Authentication Endpoints ​

Sign Up ​

Verify Signup ​

Login ​

Refresh Token ​

Get Current User ​

Forgot Password ​

Verify Forgot Password ​

Reset Password ​

Resend OTP ​

Get Dealer Application Status ​

Car Endpoints ​

Get All Cars ​

Get Car by ID ​

Create Car Listing ​

Update Car Listing ​

Delete Car Listing ​

Get My Cars ​

Advanced Car Search ​

Get Car Analytics ​

Car Interaction Endpoints ​

Like a Car ​

Get Car Views ​

Increment Car Views ​

Get Car Comments ​

Post Car Comment ​

Generate Share Link ​

Schedule Test Drive ​

Get Trending Cars ​

Car Data Endpoints ​

Get All Makes ​

Get Models by Make ​

Get Body Types ​

Get Features ​

Get Car Template ​

Get User's Liked Cars ​

Get Batch Car Stats ​

Comment Interactions ​

Like a Comment ​

Reply to Comment ​

AI Endpoints ​

Generate Car Listing ​

Enhance Description ​

Natural Language Search ​

Get AI Recommendations ​

Get Pricing Insights ​

Generate Car Description ​

Lifestyle Recommendations ​

Dealer Endpoints ​

Get All Dealers ​

Get Dealer by ID ​

Get Dealer Cars ​

Approve Dealer (Admin Only) ​

Get Pending Dealers (Admin Only) ​

Get Dealer Profile ​

Update Dealer Profile ​

Get Business Hours ​

Update Business Hours ​

Update Business Info ​

Get Dealer Statistics ​

Export Cars ​

Get Dealer Reviews ​

Submit Dealer Review ​

Customer Endpoints ​

Get Favorites ​

Add to Favorites ​

Remove from Favorites ​

YeboCars API Reference

Base URLs

Authentication

Authentication Header

Token Types

Authentication Endpoints

Sign Up

Verify Signup

Login

Refresh Token

Get Current User

Forgot Password

Verify Forgot Password

Reset Password

Resend OTP

Get Dealer Application Status

Car Endpoints

Get All Cars

Get Car by ID

Create Car Listing

Update Car Listing

Delete Car Listing

Get My Cars

Advanced Car Search

Get Car Analytics

Car Interaction Endpoints

Like a Car

Get Car Views

Increment Car Views

Get Car Comments

Post Car Comment

Generate Share Link

Schedule Test Drive

Get Trending Cars

Car Data Endpoints

Get All Makes

Get Models by Make

Get Body Types

Get Features

Get Car Template

Get User's Liked Cars

Get Batch Car Stats

Comment Interactions

Like a Comment

Reply to Comment

AI Endpoints

Generate Car Listing

Enhance Description

Natural Language Search

Get AI Recommendations

Get Pricing Insights

Generate Car Description

Lifestyle Recommendations

Dealer Endpoints

Get All Dealers

Get Dealer by ID

Get Dealer Cars

Approve Dealer (Admin Only)

Get Pending Dealers (Admin Only)

Get Dealer Profile

Update Dealer Profile

Get Business Hours

Update Business Hours

Update Business Info

Get Dealer Statistics

Export Cars

Get Dealer Reviews

Submit Dealer Review

Customer Endpoints

Get Favorites

Add to Favorites

Remove from Favorites

Send Inquiry

Get Inquiry History

Get Viewed Cars History

Get Liked Cars

Message Endpoints

Send Message

Get Conversations

Get Messages in Conversation